# What Is a SKILL.md File and How Is It Used in Claude Plugins? > Discover SKILL.md files and their role in Claude plugins. Learn how these markdown documents define reusable, step-by-step workflows for Claude to execute. - Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community) - Tags: documentation - Published: 2026-09-06 --- **A [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file is a declarative markdown document that defines a reusable, step-by-step workflow (a "skill") that Claude can execute from a plugin, combining front-matter metadata with procedural instructions that the runtime interprets directly.** This article examines the [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) format based on the official [`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community) repository. These files sit at the heart of the Claude plugin architecture, enabling developers to define complex agent behaviors without writing traditional code. --- ## The Four Core Sections of a SKILL.md File Every [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) follows a consistent structure. Based on analysis of files like [[`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)](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-wallets-upload/SKILL.md) and [[`quickdesign/skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md)](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md), the format contains four logical parts. ### 1. Front-Matter Metadata The YAML header registers the skill with Claude's runtime: ```yaml --- name: tres-wallets-upload description: Upload and onboard multiple on-chain wallets to Tres Finance compatibility: "Requires TRES Finance MCP connected with wallet:read and wallet:write scopes" --- ``` The `name` and `description` fields populate the Claude UI's skill browser. The optional `compatibility` field signals prerequisites to both the runtime and end users. ### 2. High-Level Overview A human-readable summary explains what the skill does and when to invoke it: ```markdown # TRES Wallet Upload Skill Use this skill when a user wants to bulk-import wallets from CSV or add them manually. ``` This section helps both developers and the Claude agent understand intent boundaries. ### 3. Procedural Steps The executable core consists of numbered steps that Claude follows sequentially. Steps use standardized primitives: | Primitive | Purpose | Example Usage | |-----------|---------|-------------| | `ask_user_input_v0` | Collect structured input from the user | Wallet type selection | | GraphQL calls | Fetch live schema data or execute mutations | `ParentPlatform` enum introspection | | `show_widget` | Render interactive UI components | File upload or preview tables | | Validation logic | Enforce constraints before proceeding | Address format checks, duplicate detection | Steps are labeled explicitly (e.g., `Step 0`, `Step OC-1` through `Step OC-5`) and can include conditional branching based on user choices. ### 4. Cardinal Rules Global guardrails that apply to every invocation, defined in a dedicated section: ```markdown ## Cardinal rules (read first, every time) - Always fetch live enums via GraphQL introspection; never hardcode platform values. - Never render HTML widgets; use markdown tables for all previews. - Abort immediately if any wallet address fails validation. ``` The runtime evaluates these before executing any step. A violation triggers an immediate halt, protecting against inconsistent or unsafe execution. --- ## How the Runtime Processes SKILL.md Files The Claude plugin loader implements a five-stage pipeline: 1. **Discovery** — Scans `…/skills/**/SKILL.md` paths within the plugin directory 2. **Registration** — Parses front-matter into the skill registry exposed to the UI 3. **Execution** — Matches user intent against skill descriptions and loads the corresponding file 4. **Enforcement** — Validates cardinal rules before step-by-step execution 5. **Feedback** — Renders step outputs (tables, confirmations, errors) back to the conversation This architecture separates **declaration** (what to do, written in markdown) from **implementation** (how primitives work, handled by the runtime). --- ## Minimal SKILL.md Example A complete, runnable skill requires only front-matter and two steps: ```yaml --- name: echo-uppercase description: Echoes user input in uppercase letters --- # Echo Uppercase Skill ## When to invoke - Use when the user wants to transform text to uppercase. ## Step 0 — Ask for input ```yaml question: "Please type a phrase to transform" type: single_line ``` ## Step 1 — Respond in uppercase ```yaml response: "{{ user_input | upper }}" ``` ``` The runtime implicitly maps `Step 0` to the `ask_user_input_v0` primitive, stores the result as `user_input`, and renders the templated response in `Step 1`. --- ## Real-World Example: Wallet Upload Skill The Tres Finance wallet upload skill demonstrates production-grade complexity in a single [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file: - **Step 0** — Requests wallet type via `ask_user_input_v0` - **Step OC-1 & OC-2** — Branch between file upload (`show_widget`) and manual entry - **Step OC-3** — Performs live GraphQL introspection to fetch the `ParentPlatform` enum - **Step OC-4** — Runs multi-layer validation: address format, duplicates, existing-wallet checks - **Step OC-5** — Generates a markdown preview table with error/warning annotations - **Step OC-7** — Executes the final MCP mutation after user confirmation All logic lives 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)](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-wallets-upload/SKILL.md), making the workflow version-controlled and auditable without touching plugin source code. --- ## Key SKILL.md Files in the Community Repository | File Path | Demonstrates | |-----------|--------------| | [`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) | Multi-step workflow with GraphQL, validation, and preview rendering | | [`quickdesign/skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md) | Cardinal rules, decision trees, and media generation commands | | [`testdino/skills/testdino-sessions/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/skills/testdino-sessions/SKILL.md) | Session lifecycle management and status reporting | | [`tres-finance-plugin/skills/tres-onboarding/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-onboarding/SKILL.md) | Meta-skill patterns that invoke other skills | --- ## Summary - **[`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md)** is a declarative markdown format that defines executable Claude workflows without traditional programming - The file structure combines **YAML front-matter** (metadata), **procedural steps** (executable instructions), and **cardinal rules** (global guardrails) - The runtime discovers files at `…/skills/**/SKILL.md`, registers them by description, and executes steps using built-in primitives - Skills support **conditional branching**, **GraphQL operations**, **user input collection**, and **widget rendering** within a version-controlled document --- ## Frequently Asked Questions ### What programming language are SKILL.md files written in? [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files use standard **markdown with YAML front-matter**, not a programming language. The runtime interprets the structured content and maps steps to built-in primitives like `ask_user_input_v0` or GraphQL handlers. This declarative approach lets non-developers write and review workflow logic. ### Can a skill call another skill? Yes. The [[`tres-finance-plugin/skills/tres-onboarding/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-onboarding/SKILL.md)](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-onboarding/SKILL.md) demonstrates this pattern with instructions like "Read its SKILL.md" to invoke sub-skills. The runtime resolves these references during execution. ### How do cardinal rules differ from step-level validation? **Cardinal rules** apply globally and are evaluated once before any step runs; violations abort immediately. **Step-level validation** gates progress within the sequence and can include user-facing error messages or retry loops. Both mechanisms enforce safety, but at different scopes. ### Where should SKILL.md files be placed in a plugin directory? Place each skill in its own subdirectory under `skills/`, with the filename exactly as [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md). The loader pattern `…/skills//SKILL.md` enables automatic discovery. Files outside this structure or with different names are not registered by the runtime.