What Is a SKILL.md File and How Is It Used in Claude Plugins?

A 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 format based on the official 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 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) and [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:

---
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:

# 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:

## 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:

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

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-name>/SKILL.md` enables automatic discovery. Files outside this structure or with different names are not registered by the runtime.

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