Understanding the SKILL.md File Structure in the Claude Plugins Community Repository

A SKILL.md file is a markdown-based specification that defines an invocable skill for Claude, structured with YAML frontmatter, numbered execution steps, validation tables, and GraphQL operations.

The anthropics/claude-plugins-community repository uses SKILL.md files as the canonical interface between Claude and external plugin capabilities. Every skill follows a strict, predictable architecture that enables deterministic execution of complex, multi-step workflows while maintaining safety and clarity for end users.

YAML Frontmatter and Metadata

Every SKILL.md begins with machine-readable YAML frontmatter that the plugin loader consumes to register the skill. This block uses folded style (>) for multi-line descriptions that render as single-line strings.

---
name: tres-wallets-upload
description: >
  Upload and onboard multiple on-chain wallets or exchange accounts into Tres Finance.
compatibility: "Requires TRES Finance MCP connected (https://ai.tres.finance/mcp)"
---

The frontmatter contains three critical fields: name (the skill identifier), description (human-readable summary), and compatibility (prerequisites). Following the YAML block, a standard markdown H1 title provides the human-readable display name for Claude's UI.

Execution Rules and Step Blocks

Immediately after the overview, a safety banner marked with ⚠️ EXECUTION RULE establishes the non-negotiable requirement that Claude must execute steps sequentially without skipping or reordering.

Steps are defined under H2 headings using the pattern ## Step {number} — {Description}. For example, in tres-finance-plugin/skills/tres-wallets-upload/SKILL.md, Step 0 handles wallet type selection:

## Step 0 — Ask Wallet Type

Ask the user what they would like to add to Tres.

```json
{
  "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"
}

Each step contains:
- A narrative instruction for Claude
- A fenced code block defining the exact `ask_user_input_v0` JSON payload or GraphQL operation
- Bulleted notes on conditional branching logic

## Branching Flows and Workflow Sections

Complex skills support multiple independent workflows through dedicated flow sections. When a skill handles distinct scenarios (such as on-chain vs. exchange wallets), the file separates them under H1 headings like `# ON-CHAIN FLOW` and `# EXCHANGE FLOW`.

Within each flow, steps follow the same numbered pattern but may use prefixes like `## Step OC-1 — …` (On-Chain) or `## Step EX-1 — …` (Exchange) to maintain uniqueness. This structure allows a single [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) to support divergent logic paths while keeping each individual path strictly linear.

## Validation and Error Handling Tables

Before any backend mutation occurs, skills enumerate validation rules in markdown tables. These tables specify required fields, regex patterns, duplicate detection logic, and data type constraints.

```markdown
| Field       | Rule                                 |
|------------|--------------------------------------|
| `name`     | Non-empty string                     |
| `identifier`| Non-empty string                     |
| `parentPlatform`| Must be a valid `ParentPlatform` enum |

Dynamic validation relies on introspection rather than hardcoded enums. Skills fetch live schema data using introspect("ParentPlatform") or queries like GetAllValidatedExchanges to ensure compatibility with current backend states.

Backend Operations and Preview Patterns

Skills embed exact GraphQL queries and mutations in fenced code blocks. These snippets are copied verbatim by the runtime during execution:

# Via TRES MCP introspect tool:

introspect("ParentPlatform")

mutation UpdateBatchInternalAccounts($input: UpdateBatchInternalAccountsInput!) {
  updateBatchInternalAccounts(input: $input) {
    success
    validationResults {
      row
      error
    }
  }
}

Before destructive operations, skills render plain-text markdown tables for user confirmation. The specification explicitly prohibits HTML widgets, requiring instead deterministic text previews followed by a summary line (X new | Y already exist | Z errors):

| # | Name          | Address                | Network   | Tags   | Status |

|---|--------------|------------------------|-----------|--------|--------|
| 1 | Treasury Hot | 0xABCD…1234            | ETHEREUM  | defi   | ✅ New |
| 2 | Cold Wallet  | bc1q…xyz               | BITCOIN   |        | ⚠️ Exists (ID: 12345) |

Chunking and Robustness Patterns

Large batch operations include sections describing chunking strategies—how to split payloads into manageable sizes—and how to parse validationResults arrays to surface individual row errors without failing the entire batch. This ensures deterministic error recovery and prevents timeout issues during bulk uploads.

Footer Documentation and Message Mapping

The final section typically contains a markdown table mapping specific failure scenarios to user-friendly recovery instructions. This serves as both developer documentation and a runtime reference for consistent error messaging.

Key Examples from the Repository

• tres-finance-plugin/skills/tres-wallets-upload/SKILL.md: Demonstrates branching flows for on-chain versus exchange wallets with comprehensive validation tables.
• tres-finance-plugin/skills/tres-report-create/SKILL.md: Shows a simpler linear flow without branching logic.
• testdino/skills/testdino-sessions/SKILL.md: Illustrates the same structural template applied to testing automation.
• quickdesign/skills/quickdesign/SKILL.md: Minimalist implementation confirming that even short skills maintain the full YAML-to-footer architecture.

Summary

• SKILL.md files begin with YAML frontmatter containing name, description, and compatibility fields.

• An execution rule banner enforces strict sequential step completion without skipping.

• Steps are numbered blocks containing narrative instructions and JSON/GraphQL code blocks for ask_user_input_v0 or backend operations.

• Branching flows use separate H1 sections (e.g., # ON-CHAIN FLOW) while maintaining linear step numbering within each path.

• Validation tables define required fields, regex patterns, and duplicate detection logic before any mutation.

• Introspection queries replace hardcoded enums to ensure dynamic compatibility with live backend schemas.

• Plain-text previews using markdown tables (never HTML) precede confirmation steps for destructive operations.

• tres-wallets-upload/SKILL.md serves as the canonical reference implementation in the anthropics/claude-plugins-community repository.

Frequently Asked Questions

What is the purpose of the YAML frontmatter in a SKILL.md file?

The YAML frontmatter provides machine-readable metadata that the plugin loader uses to register and display the skill. It contains the unique name identifier, a folded description string, and compatibility requirements that declare MCP dependencies or other prerequisites.

How does Claude know which step to execute next?

Step blocks follow strict numerical ordering (Step 0, Step 1, Step OC-1, etc.) preceded by an ⚠️ EXECUTION RULE banner that explicitly instructs Claude to never skip or reorder steps. Each step contains the exact JSON payload or GraphQL operation required to complete that atomic action.

Why do SKILL.md files use introspection instead of hardcoded enums?

Skills dynamically fetch live schema data using introspect("ParentPlatform") or similar queries rather than embedding static enum values. This ensures that validation rules and selection options always reflect the current backend state, preventing failures when new networks, exchanges, or platforms are added.

Can a single SKILL.md file handle multiple different workflows?

Yes. Skills support branching logic through dedicated flow sections such as # ON-CHAIN FLOW and # EXCHANGE FLOW. Each flow maintains its own linear step sequence, allowing one skill definition to handle distinct use cases while preserving the strict execution requirements within each path.

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