# How Skills Are Defined Within a Claude Plugin: Structure, Syntax, and Examples

> Learn how Claude plugin skills are defined in markdown files using YAML metadata and step-by-step conversational instructions for complex workflows.

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

---

**Claude plugin skills are defined in markdown files named [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) that contain YAML front-matter metadata describing the skill's name and description, followed by step-by-step conversational instructions that Claude follows to execute complex multi-turn workflows.**

Skills within a Claude plugin represent discrete, callable capabilities that guide users through structured interactions. Unlike traditional function calling, these skills defined within a Claude plugin leverage markdown-based instruction sets that Claude interprets at runtime, enabling sophisticated conversational flows without requiring compiled plugin code. The `anthropics/claude-plugins-community` repository demonstrates this architecture through production examples like the Tres Finance plugin.

## Plugin Architecture Overview

A Claude plugin operates as a package containing a central manifest and multiple skill definitions. Understanding the relationship between these components is essential for implementing custom functionality.

### The plugin.json Manifest

Every plugin requires a top-level **[`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)** file located at [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json). This JSON manifest describes the plugin metadata—including name, version, author, and required MCP connections—and specifies the root directory where Claude should scan for skills.

In the Tres Finance plugin example, this manifest tells Claude which directory contains the skills and what user-configurable secrets are required for authentication.

### The SKILL.md Definition File

Individual skills reside in subdirectories under `skills/<skill-name>/` and are defined in files named **[`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md)**. These markdown documents serve as both the registration interface and the runtime instruction set for Claude.

According to the source code in `anthropics/claude-plugins-community`, each [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file contains:
- YAML front-matter (lines 1–13) with metadata
- Human-readable sections defining conversational steps
- Optional references to helper scripts in `skills/<skill-name>/scripts/`

## Anatomy of a Skill Definition

The structure of a skill definition follows a specific pattern that Claude parses to register and execute the capability.

### YAML Front-Matter Metadata

The file must begin with a YAML front-matter block delimited by triple dashes. This metadata registers the skill with Claude's tool 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 front-matter contains three critical fields:
- **`name`** – The unique identifier Claude uses when the Skill tool is invoked (e.g., `skill: tres-wallets-upload`)
- **`description`** – A concise, user-facing explanation that Claude can present as a trigger phrase
- **`compatibility`** – Human-readable requirements indicating necessary external services; Claude displays this when dependencies are unavailable

### Conversational Flow Steps

Following the front-matter, the markdown content defines the step-by-step conversational flow. Claude interprets these sections literally to drive user interactions.

The flow organizes into numbered steps (e.g., `## Step 0`, `## Step OC-1`, `## Step OC-4`) that can include:

- **`ask_user_input_v0`** calls defining questions, options, and response types
- Data processing instructions (e.g., "Read the file with pandas / openpyxl")
- GraphQL queries fetching live schema values or checking existing entities
- **Hard-gate warnings** enforcing step ordering (e.g., "Do NOT render this preview until Step OC-4 is complete")

### Script Integration

When skills require non-trivial computation, they reference helper scripts stored in `skills/<skill-name>/scripts/`. Claude executes these via the **`run`** tool with arguments defined by the skill author.

For example, the `tres-report-analyzer` skill invokes [`scripts/analyze_report.py`](https://github.com/anthropics/claude-plugins-community/blob/main/scripts/analyze_report.py) to parse uploaded XLSX files:

```bash
python skills/tres-report-analyzer/scripts/analyze_report.py "/path/to/uploaded/file.xlsx" --output /path/to/output.json

```

## How Claude Discovers and Loads Skills

When loading a plugin, Claude performs a directory scan based on the path specified in [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json). The discovery process follows this sequence:

1. **Scan** the plugin directory for files named exactly [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md)
2. **Parse** the YAML front-matter to register the skill's `name` and `description` with the Skill tool
3. **Store** the complete markdown content as the skill's instruction set
4. **Enable** invocation via the Skill tool using the registered name (e.g., `skill: example-skill`)

This registration makes the skill available at runtime, where Claude uses the step definitions to conduct structured conversations with users.

## Practical Implementation Examples

### Invoking a Skill via the Claude API

Developers trigger skills programmatically by specifying the skill name in the tools parameter:

```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 initiates the wallet-upload flow defined in SKILL.md

```

When invoked, Claude reads the `tres-wallets-upload` entry from [`skills/tres-wallets-upload/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/skills/tres-wallets-upload/SKILL.md) and executes the defined steps sequentially.

### Minimal SKILL.md Template

The following skeleton demonstrates the minimal structure required for a valid skill definition:

```markdown
---
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 workflows. It references [`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) to extract metrics from uploaded spreadsheets:

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

```

The script returns JSON data that the skill subsequently uses to compose its final response to the user.

## Summary

- **Skills defined within a Claude plugin** reside 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 at [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) tells Claude where to locate skills and what dependencies are required.
- Each skill requires a **`name`**, **`description`**, and **`compatibility`** field in its YAML front-matter for registration.
- Conversational flows use numbered steps (Step 0, Step 1, etc.) with hard-gates to enforce execution order.
- Optional **helper scripts** in `skills/<skill-name>/scripts/` extend capabilities via the `run` tool.
- Claude scans for [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files at load time and stores the markdown content as executable instruction sets.

## Frequently Asked Questions

### What file format is used to define Claude plugin skills?

Claude plugin skills use **markdown files named [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md)** with YAML front-matter. This format combines machine-readable metadata (the YAML block) with human-readable instructions (the markdown content) that Claude interprets at runtime. No compilation is required for the skill definition itself.

### How does Claude know which directory contains the skills?

Claude reads the **[`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)** manifest located at [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) to determine the plugin root directory. It then recursively scans this directory for any file named [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md), parsing each one to register available skills with the Skill tool.

### Can Claude plugin skills execute external scripts?

Yes. Skills can reference helper scripts stored in `skills/<skill-name>/scripts/` directories. These scripts execute via Claude's **`run`** tool when the skill definition contains script invocation commands. For example, the `tres-report-analyzer` skill executes Python scripts to process uploaded XLSX files.

### What is the purpose of the compatibility field in SKILL.md?

The **`compatibility`** field in the YAML front-matter specifies external service requirements (such as MCP connections) in human-readable text. Claude displays this information to users when the required service is unavailable, helping them understand prerequisites before attempting to invoke the skill.