Claude Plugin Skill Markdown File Structure: Complete Guide to SKILL.md Format

A Claude plugin skill is defined in a single SKILL.md file located under a plugin's skills/ folder, requiring mandatory YAML front-matter with name and description fields, followed by an H1 title, optional invocation guidelines, cardinal rules in block quotes, and a numbered step-by-step procedure.

The anthropics/claude-plugins-community repository establishes a canonical format for defining Claude plugin skills. Understanding the precise structure of a Claude plugin skill markdown file is essential for developers building extensible AI workflows, as the framework relies on specific metadata and section conventions to discover and execute skills correctly.

Required Components of a SKILL.md File

Every skill must implement three core structural elements for the plugin loader to recognize and process the file.

YAML Front-Matter

The file must begin with a YAML block containing exactly two fields: name (the skill identifier) and description (a concise summary of functionality). Without this metadata, the skill remains invisible to the plugin framework.

---
name: quickdesign
description: Use the quickdesign CLI to generate AI media with structured prompts
---

Title and Overview

Immediately following the front-matter, an H1 heading (#) must mirror the name field from the YAML block. A brief overview paragraph (one to two sentences) should restate the skill's purpose and indicate when Claude should invoke it.

# QuickDesign CLI skill

This skill teaches Claude how to plan and execute AI media generation workflows using the QuickDesign command-line interface.

Step-by-Step Procedure

The operational core consists of numbered steps (## Step X — Description). Each step represents an atomic action—whether calling an API, requesting user input, or executing a bash command. According to the source code in files like tres-finance-plugin/skills/tres-wallets-upload/SKILL.md, these sections contain the only portions where Claude is expected to call external tools.

## Step 0 — Ask Wallet Type

```json
{
  "tool": "ask_user_input_v0",
  "args": {
    "question": "What type of wallet are you importing?",
    "type": "single_line"
  }
}

Step 1 — Parse CSV Data

Validate the uploaded file contains an address column before proceeding.

## Optional but Recommended Sections

Production-ready skills in the repository frequently include additional structural elements to improve reliability and maintainability.

### When-to-Invoke Guidelines

Large plugins containing multiple skills benefit from a bulleted **When-to-Invoke** section that explicitly maps user intents to skill activation. This helps the model route requests correctly when multiple capabilities overlap.

```markdown

## When to Invoke

- "Generate a marketing video"
- "Create talking avatar content"
- "Produce UGC-style media"

Cardinal Rules and Global Constraints

High-level constraints that apply to every step should be formatted as Markdown block quotes (>) with warning indicators. The quickdesign/skills/quickdesign/SKILL.md file demonstrates this pattern for enforcing default model parameters across all operations.

## Cardinal rules (read first, every time)

> 0. **Default video model = `seedance-2.0-r2v`** unless user specifies otherwise
> 1. **Always use `@Image1` / `@Audio1` syntax** for referencing uploaded assets
> 2. **Validate aspect ratios** before rendering (9:16 for mobile, 16:9 for desktop)

Error-Handling and Recovery

Robust skills include tables mapping failure modes to remediation steps. This pattern appears in the Tres Finance wallet upload skill, where GraphQL errors and CSV validation issues are documented with specific recovery actions.

## Error Handling

| Situation | What to do |
|-----------|-----------|
| CSV has no address column | Ask user to re-export with headers included |
| GraphQL returns 401 | Prompt for API key re-authentication |
| Duplicate wallet detected | Skip entry and log warning to user |

References and Supporting Documentation

Complex skills may link to auxiliary Markdown files stored in a references/ subdirectory. These files contain detailed specifications, regex patterns, or external guidelines that would clutter the main procedure.

## References

- [voice-continuity.md](references/voice-continuity.md) - Tone consistency guidelines
- [graphql-schema.md](references/graphql-schema.md) - Available query types

Real-World Examples from the Repository

The anthropics/claude-plugins-community repository provides reference implementations demonstrating both minimal and complex skill structures.

Minimal Skill Skeleton

The eli5/skills/eli5/SKILL.md file illustrates the bare-bones structure required for a functional skill:

---
name: eli5
description: Explain complex topics like I'm five years old
---

# ELI5 Skill

Use this skill when the user asks for simplified explanations of technical concepts.

## Step 0 — Identify Core Concept

Ask clarifying questions until you understand the specific topic to explain.

## Step 1 — Generate Explanation

Provide an analogy suitable for a five-year-old's understanding level.

---

Complex Workflow Example

The quickdesign/skills/quickdesign/SKILL.md demonstrates advanced features including cardinal rules, bash command integration, and reference linking:

---
name: quickdesign
description: Use the quickdesign CLI to generate AI media …
---

# QuickDesign CLI skill

## Cardinal rules (read first, every time)

> 0. **Default video model = `seedance-2.0-r2v`** …  
> 1. **Use `@Image1` / `@Audio1` …**  

## Step 0 — Confirm Model Choice

```bash
quickdesign video models   # query the live registry

Step 1 — Collect References

Ask the user to upload:

• Product image (@Image1)
• Avatar image (@Image2)

Step 2 — Generate Segment 1

quickdesign video generate \
  --provider seedance \
  --reference-image product.jpg \
  --reference-image avatar.jpg \
  --duration 12 --aspect-ratio 9:16 \
  -p '@Image2 speaks: "Hello!" No music score. No subtitles.' \
  -o seg1.mp4 --wait

---

## Summary

- A valid **Claude plugin skill markdown file** requires YAML front-matter with `name` and `description` fields, an H1 title matching the name, and numbered procedural steps.
- **Optional sections** such as When-to-Invoke, Cardinal Rules, and Error Handling improve skill robustness and model routing accuracy.
- All executable logic belongs in the **step sections**, where tool calls like `ask_user_input_v0` or bash commands are embedded in fenced code blocks.
- Reference external documentation using relative links to a `references/` directory to keep the main skill file focused on procedure.
- End the file with a horizontal rule (`---`) to mark the boundary of the skill definition.

## Frequently Asked Questions

### What happens if the YAML front-matter is missing from a SKILL.md file?

The plugin framework will not discover or load the skill. According to the repository implementation, the `name` and `description` fields in the YAML block are mandatory metadata used for skill indexing and presentation in the Claude interface.

### Can a single skill step contain multiple tool calls?

While each step should represent a logical atomic action, a step may contain multiple tool calls if they are dependent operations. However, the repository convention shown in [`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) favors breaking complex sequences into distinct numbered steps to maintain clarity and error isolation.

### How does the When-to-Invoke section affect Claude's behavior?

The When-to-Invoke section provides the model with explicit intent-matching criteria. When a user query matches one of the listed patterns, Claude prioritizes activating that specific skill over general knowledge or other available skills in the plugin directory.

### Where should reference documentation be stored within the plugin structure?

Auxiliary documentation belongs in a `references/` subdirectory adjacent to the [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file, as demonstrated in the `quickdesign/skills/quickdesign/references/` path. This keeps the main skill file clean while allowing deep linking to technical specifications using relative Markdown links like `[voice-continuity.md](references/voice-continuity.md)`.

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