SKILL.md File Structure: The Complete Technical Guide for Claude Plugins

A SKILL.md file defines a declarative, executable skill that Claude invokes through YAML metadata, sequentially numbered step blocks, and canonical GraphQL or JSON code specifications.

In the anthropics/claude-plugins-community repository, the SKILL.md file serves as the single source of truth for plugin capabilities. This markdown-based schema instructs Claude on how to execute complex multi-step workflows—from uploading crypto wallets to generating financial reports—while enforcing strict safety rules and validation logic. Understanding this structure is essential for developers building deterministic AI automations that interact with external APIs.

Anatomy of a SKILL.md File

Every SKILL.md in the repository follows a rigid, ten-section architecture designed for both human readability and machine parsing. The layout ensures Claude can execute tasks sequentially without hallucinating steps or skipping validation.

YAML Front-Matter Metadata

The file opens with a YAML block enclosed by triple dashes. This section provides machine-readable metadata that the plugin loader uses to register and describe the skill.

---
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 description field uses a folded block scalar (>) to allow multi-line text while preserving a single-line string in the parsed YAML.

Human-Readable Title and Overview

Immediately following the front-matter, a level-one heading provides the display title, followed by free-form paragraphs explaining the skill's intent and high-level flow.

# Tres Wallet Upload

This skill guides users through uploading on-chain wallets or exchange accounts. It handles branching logic for different asset types and enforces validation before any data mutation.

Execution Rule Banner

A critical safety component appears next: a blockquote beginning with ⚠️ EXECUTION RULE. This banner explicitly instructs Claude to treat the skill as a sequential checklist and never skip or reorder steps.

> ⚠️ **EXECUTION RULE**: Execute every step in the exact order listed below. Do not proceed to the next step until the current step is completed.

Sequential Step Blocks

The core logic resides in numbered step headings such as ## Step 0 — Ask Wallet Type or ## Step OC-1 — Validate On-Chain Address. Each step contains:

• A narrative description of the action
• A fenced code block specifying the exact API payload (typically ask_user_input_v0 JSON or GraphQL)
• Conditional logic notes for branching

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

Step numbering uses zero-indexed integers (Step 0) for initialization and flow-specific prefixes (Step OC-1, Step EX-1) for branched paths.

Flow-Specific Sections

Skills with branching logic define separate top-level headings such as # ON-CHAIN FLOW or # EXCHANGE FLOW. Each flow repeats the step-by-step pattern independently, allowing a single skill definition to support multiple workflows while keeping each execution path linear and deterministic.

Validation and Error-Handling Tables

Before any mutation reaches the backend, the skill enumerates validation rules in markdown tables. These specify required fields, regex patterns per network, duplicate detection logic, and existing-wallet checks.

| Field          | Rule                                      |
|----------------|-------------------------------------------|
| `name`         | Non-empty string                          |
| `identifier`   | Non-empty string                          |
| `parentPlatform`| Must be a valid `ParentPlatform` enum    |
| `address`      | Regex match per network protocol          |

Preview and Confirmation Steps

Skills must render a plain-text markdown table summarizing user-supplied data before execution. This step explicitly forbids HTML widgets, displaying instead a formatted table with status indicators (✅ New, ⚠️ Exists, ❌ Error) and a final confirmation prompt.

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

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

GraphQL Operations

The specification embeds full GraphQL snippets in fenced code blocks, documenting exact backend operations. These include introspection queries for dynamic schema fetching and mutations for data persistence.

# Via TRES MCP introspect tool:

introspect("ParentPlatform")

mutation UpdateBatchInternalAccounts($input: BatchUpdateInput!) {
  updateBatchInternalAccounts(input: $input) {
    validationResults {
      valid
      errors {
        field
        message
      }
    }
  }
}

Chunking and Result Handling

For large datasets, the skill defines chunking strategies—how to split batches, parse validationResults arrays, and surface granular errors back to the user without failing the entire operation.

Footer and Error Reference

The file concludes with a markdown table mapping failure scenarios to user-friendly recovery instructions, providing a deterministic error-recovery path for both the runtime and end users.

Key Design Principles

The SKILL.md structure enforces five critical architectural constraints that distinguish it from generic documentation:

Strict Sequential Ordering — Every step is explicitly numbered, and the execution rule banner prevents Claude from reordering operations or skipping validation checks.

Declarative Interaction Specs — All user prompts and API calls are represented as canonical JSON or GraphQL code blocks, making the skill self-contained and machine-parsable without ambiguity.

Dynamic Data Fetching — Skills never hard-code enums or lists. Instead, they invoke introspect or query operations to fetch live schema data, ensuring the skill remains valid as APIs evolve.

Plain-Text UI Preference — Wherever previews are required, the skill mandates markdown tables over HTML widgets, maintaining deterministic rendering across different client environments.

Comprehensive Validation — Input validation is enumerated explicitly in tables, ensuring the skill can reject malformed data before any network call is attempted.

Real-World Examples in the Repository

The anthropics/claude-plugins-community repository contains several canonical implementations demonstrating this structure:

• tres-finance-plugin/skills/tres-wallets-upload/SKILL.md — A complex skill with branching on-chain and exchange flows, demonstrating validation tables and chunked uploads.
• tres-finance-plugin/skills/tres-report-create/SKILL.md — A linear workflow showing simplified step sequencing for financial report generation.
• testdino/skills/testdino-sessions/SKILL.md — Illustrates the same structural template applied to testing automation.
• quickdesign/skills/quickdesign/SKILL.md — A minimalist skill highlighting that even short definitions include all mandatory sections.

Summary

• Every SKILL.md in the anthropics/claude-plugins-community repository follows a standardized ten-section layout.
• The file begins with YAML front-matter for metadata and includes a mandatory ⚠️ EXECUTION RULE banner to enforce sequential processing.
• Logic is broken into atomic, numbered steps (Step 0, Step OC-1) containing canonical JSON payloads or GraphQL operations.
• Validation rules, error-handling tables, and plain-text previews ensure deterministic execution and safe user interactions.
• Skills reference specific file paths like tres-wallets-upload/SKILL.md to demonstrate real-world implementation patterns.

Frequently Asked Questions

What is the purpose of the YAML front-matter in SKILL.md?

The YAML block at the top of every SKILL.md provides machine-readable metadata including the skill's name, description, and compatibility requirements. The plugin loader parses this header to register the skill in Claude's available capabilities list without executing the full markdown content.

How does Claude handle branching logic in SKILL.md files?

Branching is implemented through flow-specific top-level headings such as # ON-CHAIN FLOW or # EXCHANGE FLOW. Each branch contains its own independent sequence of numbered steps (e.g., Step OC-1, Step EX-1), ensuring that execution within any given path remains strictly linear while allowing the skill to support multiple distinct workflows.

Why do SKILL.md files use plain-text markdown tables instead of HTML widgets?

The structure explicitly forbids HTML widgets in favor of markdown tables for data previews and validation displays. This constraint ensures deterministic rendering across different client environments and prevents potential security or layout issues that could arise from arbitrary HTML execution, maintaining a consistent user experience.

What happens if a step in SKILL.md fails validation?

The skill defines error scenarios in dedicated validation tables and footer sections mapping failure conditions to recovery instructions. Before any mutation reaches the backend, the skill checks validationResults arrays, and if errors are detected, it surfaces specific field-level messages to the user without proceeding to subsequent steps, enforcing a fail-safe execution model.

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