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

> Learn how Claude plugin skills are defined using declarative SKILL.md files. This guide explains step-by-step workflows without code for efficient plugin development.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-09-05

---

**Skills in Claude plugins are defined as **declarative markdown files** ([`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file declares the skill's identity and discoverability:

```yaml
---
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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) | Plugin‑level manifest | [`quickdesign/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json) |
| `skills/*/SKILL.md` | Individual skill definitions | [`quickdesign/skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md) |

### Real‑World Examples from the Codebase

**Minimal skill:** [`eli5/skills/eli5/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/eli5/skills/eli5/SKILL.md) — demonstrates the simplest possible structure.

**Complex workflow:** [`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) — 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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) for metadata (name, version, author)
2. **Skill enumeration** — Scans the `skills/` directory, loading each [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/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

```markdown
---
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

```yaml
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

```text
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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) | Top‑level plugin descriptor with metadata |
| [`quickdesign/skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md) | Production‑ready media generation skill |
| [`eli5/skills/eli5/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/eli5/skills/eli5/SKILL.md) | Minimal viable skill definition |
| [`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) | Complex workflow with validation and GraphQL |
| [`testdino/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md)) could theoretically add [`quickdesign/skills/quickedit/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files. The runtime likely uses last‑found‑wins or throws a loading error, though the repository examples show no collision handling.