# How Are Skills Defined in Claude Plugins: Complete Guide to SKILL.md Structure

> Learn how Claude plugins define skills using SKILL.md files with YAML metadata and conversational instructions. Discover the structure and integrate them seamlessly.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: deep-dive
- Published: 2026-09-09

---

**Skills in Claude plugins are defined via markdown files named [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) that contain YAML front‑matter metadata and step‑by‑step conversational instructions, discovered through a top‑level [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest.**

The `anthropics/claude-plugins-community` repository demonstrates how to extend Claude's capabilities through a structured plugin architecture. Understanding how skills are defined in Claude plugins allows developers to create reusable, interactive workflows without modifying core plugin code. Each skill is a self‑contained markdown document that Claude parses to drive structured conversations with users.

## The Plugin Architecture: plugin.json and SKILL.md

A Claude plugin is organized as a package with two primary components that define how skills are discovered and executed.

The **[`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)** manifest serves as the entry point. Located at [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json), this file describes the plugin metadata—including name, version, author, and required MCP connections—and specifies the directory where Claude should scan for skill definitions.

The **[`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md)** files contain the actual skill logic. These markdown documents reside in subdirectories under the skills folder (e.g., [`skills/tres-wallets-upload/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/skills/tres-wallets-upload/SKILL.md)). Each file defines a single skill's behavior, including its conversational flow, input validation, and optional script execution.

Optional **`scripts/`** directories within skill folders store helper scripts—typically Python files—that perform complex data processing or API interactions referenced by the skill definition.

## Anatomy of a Skill Definition File

Understanding how skills are defined in Claude plugins requires examining the internal structure of [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files, which consist of three distinct layers.

### YAML Front-Matter Configuration

Every skill definition begins with a YAML front‑matter block enclosed by triple dashes. This header registers the skill with Claude's system:

```yaml
---
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 **`name`** field provides the identifier used when invoking the **Skill** tool. The **`description`** offers a user‑facing explanation that Claude can present as a trigger phrase. The **`compatibility`** field indicates required external services, allowing Claude to display warnings if dependencies are unavailable.

### Conversational Flow and Steps

Below the front‑matter, the markdown content defines the conversational flow through numbered sections. Claude follows these instructions literally, treating them as an instruction set for user interactions.

The flow is divided into **steps** (e.g., `Step 0`, `Step OC‑1`, `Step OC‑4`) that can contain:

- **`ask_user_input_v0`** calls that define questions, available options, and expected response types
- Data processing instructions (e.g., "Read the file with pandas / openpyxl")
- GraphQL queries that fetch live schema values or verify existing entities
- **Hard‑gate warnings** (e.g., "Do NOT render this preview until Step OC‑4 is complete") that enforce strict step ordering

### Script Integration

When skills require computation beyond conversation, they reference helper scripts located in `skills/<skill-name>/scripts/`. The skill definition specifies script execution via standard code blocks, which Claude executes through the **`run`** tool. For example, the `tres-report-analyzer` skill calls [`scripts/analyze_report.py`](https://github.com/anthropics/claude-plugins-community/blob/main/scripts/analyze_report.py) to parse uploaded XLSX files and return JSON data for further processing.

## How Claude Discovers and Loads Skills

When a plugin loads, Claude initiates a discovery process to identify available capabilities.

First, Claude scans the directory specified in [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) for any file named exactly **[`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md)**. For each file discovered, the system:

1. Parses the YAML front‑matter to register the **name** and **description**
2. Stores the full markdown content as the skill's **instruction set**
3. Makes the skill callable through the **Skill** tool using the syntax `skill: <name>` (e.g., `skill: tres-wallets-upload`)

At runtime, Claude uses the step definitions within the instruction set to drive structured conversations. The skill logic lives entirely in the markdown file; no compiled code is required for the definition itself, though optional scripts extend functionality.

## Practical Implementation Examples

These examples from the `anthropics/claude-plugins-community` repository demonstrate how to implement and invoke skills.

### Triggering a Skill via the Skill Tool

To invoke a defined skill programmatically, reference it by name in the tools array:

```python

# Pseudo-code for a Claude client

response = claude.run(
    prompt="I need to add new wallets to Tres.",
    tools=[{
        "type": "skill",
        "name": "tres-wallets-upload"
    }]
)
print(response.message)   # Claude starts the wallet-upload flow defined in SKILL.md

```

Claude reads the `tres-wallets-upload` entry from the corresponding [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) and follows the steps defined there.

### Minimal SKILL.md Template

Create a new skill by following this skeleton structure:

```yaml
---
name: example-skill
description: Demonstrates the minimal structure of a skill definition.
compatibility: "Requires Example MCP"
---

# Example Skill

## Step 0 — Ask a question

Ask the user for a value using `ask_user_input_v0`:

```yaml
question: "What is the target entity?"
type: single_line

```

## Step 1 — Perform an action

Run a helper script located at `scripts/do_something.py`:

```bash
python scripts/do_something.py "{{user_input}}"

```

```

### Executing Helper Scripts

The `tres-report-analyzer` skill demonstrates file processing by executing a Python script:

```bash
python /path/to/skill/scripts/analyze_report.py "/path/to/uploaded/file.xlsx" --output /path/to/output.json

```

The script reads the Excel file, extracts metrics, and returns JSON results that the skill uses to compose its final response.

## Summary

- **Skills are defined in [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files** containing YAML front‑matter and markdown instructions
- The **[`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest** tells Claude where to locate skill definitions
- **YAML front‑matter** registers the skill name, description, and compatibility requirements
- **Step‑by‑step markdown sections** drive conversational workflows through numbered steps
- **Optional scripts** in `skills/<name>/scripts/` extend capabilities via the `run` tool
- Claude discovers skills automatically by scanning for [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files at plugin load time

## Frequently Asked Questions

### What file format is required for Claude plugin skills?

Claude plugin skills must be defined in markdown files named exactly [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md). These files must begin with a YAML front‑matter block containing `name`, `description`, and optional `compatibility` fields. The remainder of the file contains standard markdown that Claude interprets as conversational instructions.

### Can a Claude skill execute external code?

Yes. Skills can reference helper scripts located in a `scripts/` subdirectory within the skill folder. These scripts—typically Python or bash files—are executed via Claude's **`run`** tool as specified in the skill's markdown instructions. For example, [`skills/tres-report-analyzer/scripts/analyze_report.py`](https://github.com/anthropics/claude-plugins-community/blob/main/skills/tres-report-analyzer/scripts/analyze_report.py) processes uploaded Excel files.

### How does Claude know which skills are available?

Claude discovers skills by scanning the directory specified in the **[`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json)** manifest for any file named [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md). It parses the YAML front‑matter of each file to register the skill name and description, making it available through the **Skill** tool without requiring additional configuration.

### What are hard-gate warnings in skill definitions?

Hard‑gate warnings are explicit instructions within a skill's markdown that prevent Claude from proceeding until specific steps are completed. For example, a skill might include the instruction "Do NOT render this preview until Step OC‑4 is complete," ensuring users provide required inputs before viewing sensitive data or executing destructive operations.