How Are Skills Defined in a Claude Plugin? The Complete Guide to SKILL.md Files

Skills in Claude plugins are defined as declarative markdown files (SKILL.md) with YAML front‑matter, stored in a skills/ directory, and executed as step‑by‑step workflows without requiring any code.

Every Claude plugin is essentially a collection of reusable skills. Whether you're building a simple greeting bot or a complex multi‑step financial workflow, understanding how skills are defined is essential to creating effective plugin experiences. This guide breaks down the exact structure, file locations, and execution model used in the anthropics/claude-plugins-community repository.

The Two‑Part Skill Architecture

Each skill consists of a YAML front‑matter block followed by a markdown body. This declarative approach eliminates the need for traditional programming while enabling sophisticated conversational flows.

Front‑Matter: Skill Metadata

The YAML header at the top of every SKILL.md file declares the skill's identity and discoverability:

---
name: quickdesign
description: Generate AI videos, images, and avatars with custom voices and captions.
---

Key front‑matter fields include:

• name – The canonical identifier that becomes the slash command (e.g., /quickdesign)
• description – Natural‑language trigger that helps Claude match user intent to the skill
• compatibility (optional) – API version or runtime requirements

Body: The Execution Workflow

Everything after the front‑matter defines step‑by‑step instructions that Claude follows when the skill is invoked. The body supports:

• ask_user_input_v0 directives for interactive prompts
• GraphQL queries and mutations for external API calls
• Conditional logic, validation rules, and preview tables
• Template variables like {{user_input}} for dynamic responses

Where Skills Live in the Repository

The anthropics/claude-plugins-community repository organizes skills in a predictable hierarchy:

Location	Purpose	Example Path
.claude-plugin/plugin.json	Plugin‑level manifest	quickdesign/.claude-plugin/plugin.json
skills/*/SKILL.md	Individual skill definitions	quickdesign/skills/quickdesign/SKILL.md

Real‑World Examples from the Codebase

Minimal skill: eli5/skills/eli5/SKILL.md — demonstrates the simplest possible structure.

Complex workflow: tres-finance-plugin/skills/tres-wallets-upload/SKILL.md — shows validation, GraphQL introspection, and batch mutations.

Skill Loading and Execution Flow

When Claude loads a plugin, the runtime follows this precise sequence:

1. Plugin discovery — Parses .claude-plugin/plugin.json for metadata (name, version, author)
2. Skill enumeration — Scans the skills/ directory, loading each SKILL.md
3. Registration — Extracts the name from front‑matter to create the /skill-name command
4. Execution — Matches user requests against skill descriptions, then executes markdown steps in order

This declarative execution model means the skill body is interpreted, not compiled. Claude reads the markdown instructions and performs actions accordingly—including respecting "hard‑gate" confirmation rules embedded in the workflow.

Complete Skill Definition Examples

Example 1: Basic Greeting Skill

---
name: greet
description: Ask the user for their name and say hello.
---

# Greet Skill

## Step 0 – Ask for the name

```yaml
question: "What is your name?"
type: free_text

Step 1 – Respond

response: "Hello, {{user_input}}! Nice to meet you."

Placed at [`my-plugin/skills/greet/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/my-plugin/skills/greet/SKILL.md), this exposes a `/greet` command.

### Example 2: Multi‑Step Selection Skill

From [`tres-finance-plugin/skills/tres-wallets-upload/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-wallets-upload/SKILL.md):

```markdown
---
name: tres-wallets-upload
description: |
  Upload and onboard multiple on-chain wallets or exchange accounts into Tres Finance.
---

# TRES Wallet Upload Skill

## Step 0 — Ask Wallet Type

question: "What would you like to add to Tres?"
options:
  - "On-Chain Wallets (Ethereum, Solana, Bitcoin, etc.)"
  - "Exchange Accounts (Binance, Coinbase, Kraken, etc.)"
type: single_select

Subsequent steps (not shown) handle GraphQL validation, preview tables, and final submission—all without executable code.

Example 3: Invoking a Skill in Practice

User: /quickdesign generate a 30‑second talking‑avatar video about coffee.
Claude: (recognizes `quickdesign` skill) → loads `quickdesign/skills/quickdesign/SKILL.md`
Claude: Executes defined steps: plan summary → voice continuity check → generation → preview

Key Files for Reference

File Path	What It Demonstrates
.claude-plugin/plugin.json	Top‑level plugin descriptor with metadata
quickdesign/skills/quickdesign/SKILL.md	Production‑ready media generation skill
eli5/skills/eli5/SKILL.md	Minimal viable skill definition
tres-finance-plugin/skills/tres-wallets-upload/SKILL.md	Complex workflow with validation and GraphQL
testdino/.claude-plugin/plugin.json	Non‑media plugin manifest example

Creating Your First Skill

To define a new skill in your Claude plugin:

1. Create a folder under skills/ with your desired command name
2. Add SKILL.md with YAML front‑matter declaring name and description
3. Write the workflow body using markdown sections for each step
4. Include ask_user_input_v0 directives for interactivity
5. Reference {{user_input}} or other template variables for dynamic content
6. Test with /your-skill-name in a Claude session

Summary

• Skills are defined in SKILL.md files with YAML front‑matter and markdown workflow bodies
• Front‑matter declares metadata: name becomes the slash command, description enables intent matching
• Body contains executable instructions: prompts, API calls, validations, and responses
• No code required: The declarative markdown architecture handles execution via Claude's runtime
• Skills live in skills/*/SKILL.md and are discovered automatically when the plugin loads

Frequently Asked Questions

What file extension must a skill definition use?

A skill definition must use .md (markdown). The specific filename is always SKILL.md inside its skill folder, not .yaml or any other extension. The YAML front‑matter is embedded within the markdown file, not separate.

Can a plugin have multiple skills?

Yes. A single plugin can contain dozens of skills, each in its own subfolder under skills/. For example, the QuickDesign plugin (quickdesign/skills/quickdesign/SKILL.md) could theoretically add quickdesign/skills/quickedit/SKILL.md as a companion skill, both registered under the same plugin manifest.

How does Claude know which skill to execute?

Claude matches user requests against the description field in each skill's front‑matter using semantic similarity. Explicit slash commands like /quickdesign bypass this matching and invoke the skill directly by its canonical name.

What happens if two skills have the same name?

The behavior is undefined—plugin authors should ensure unique name values across all SKILL.md files. The runtime likely uses last‑found‑wins or throws a loading error, though the repository examples show no collision handling.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}