# How are skills defined within a Claude plugin: The complete SKILL.md and plugin.json anatomy

> Learn how Claude plugin skills are defined using SKILL.md and plugin.json. Understand the anatomy of YAML metadata and Claude's step-by-step execution for powerful AI conversations.

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

---

**Skills in a Claude plugin 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 describing the skill's identity, followed by structured instructions that Claude executes step-by-step during conversations.**

The `anthropics/claude-plugins-community` repository demonstrates a plugin architecture where capabilities are declared through declarative configuration rather than compiled code. Each skill is a self-contained unit consisting of metadata, conversational logic, and optional helper scripts that Claude loads dynamically from a designated directory.

## Core components of a Claude plugin

A Claude plugin package follows a strict directory structure with two mandatory components: a manifest file and one or more skill definition files.

### The plugin.json manifest

Every plugin contains a top-level [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) file that serves as the entry point. This JSON manifest declares the plugin's metadata, version, author information, required MCP (Model Context Protocol) connections, and user-configurable secrets. Crucially, it specifies the root directory where Claude should scan for skill definitions.

For example, in the `tres-finance-plugin` within the `anthropics/claude-plugins-community` repository, the manifest resides at [`tres-finance-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json). This file tells Claude to look for [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files in the plugin's subdirectories to discover available capabilities.

### The SKILL.md definition file

Individual skills are defined in files named exactly [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md), typically located within `skills/<skill-name>/` directories. Each file combines machine-readable YAML metadata with human-readable markdown instructions that guide Claude's behavior during execution.

## Anatomy of a skill definition file

A [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file consists of three distinct sections: YAML front-matter for registration, markdown instructions for conversation flow, and optional script references for complex operations.

### YAML front-matter metadata

The first 13 lines of a [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file contain a YAML block enclosed by triple dashes. This block 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 serves as the unique identifier Claude uses when the **Skill** tool is invoked. The **`description`** provides user-facing text that Claude can present as trigger phrases or tooltips. The **`compatibility`** field indicates required external services; Claude displays this warning to users if the service is unavailable, preventing confusion when dependencies are missing.

### Conversational flow and steps

Following the YAML block, the markdown content defines the step-by-step conversational flow. Claude follows these instructions literally, executing them in sequence to drive structured interactions with users. The flow is organized into numbered **steps** (e.g., `Step 0`, `Step OC-1`, `Step OC-4`) and can include:

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

### Script references and execution

When a skill requires non-trivial computation or external API interactions, the markdown references helper scripts stored in a `scripts/` subdirectory within the skill folder. For instance, the `tres-report-analyzer` skill located at [`skills/tres-report-analyzer/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/skills/tres-report-analyzer/SKILL.md) invokes Python scripts to parse uploaded XLSX files:

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

```

Claude executes these scripts via the **`run`** tool, passing parameters defined in the skill's instructions. The script at [`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 the file, extracts metrics, and returns JSON that the skill uses to compose its final response.

## How Claude discovers and loads skills

When a plugin is loaded, Claude performs a directory scan of the location specified in [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json). For every file named exactly [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) found in the scan:

1. Claude parses the YAML front-matter to register the skill's **name** and **description** in the tool registry
2. The full markdown content is stored as the skill's **instruction set** in memory
3. The skill becomes callable through the **Skill tool** using the identifier defined in the front-matter (e.g., `skill: tres-wallets-upload`)

At runtime, when a user triggers a skill, Claude retrieves the stored instruction set and executes the defined steps. The skill's logic lives entirely in the markdown file; no compiled plugin code is required for the definition itself, making skills lightweight and easy to modify.

## Practical examples

### Invoking a skill from a Claude client

Developers trigger defined skills by referencing the skill name in the tools array when calling Claude:

```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 reads the `tres-wallets-upload` entry from the corresponding [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) and initiates the wallet-upload flow defined in the steps.

### Minimal skill template

Below is a skeleton structure for creating a new skill:

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

```

```

### Integrating helper scripts

The `tres-wallets-upload` skill in the `anthropics/claude-plugins-community` repository demonstrates complex flow control with multiple validation steps before accepting data. Conversely, the `tres-report-analyzer` skill shows how to handle file uploads by delegating parsing to [`scripts/analyze_report.py`](https://github.com/anthropics/claude-plugins-community/blob/main/scripts/analyze_report.py), keeping the skill definition readable while handling complex Excel processing externally.

## Summary

- Skills are defined in [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files containing YAML front-matter for metadata and markdown for 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) configures the plugin and points Claude to the skills directory
- YAML front-matter requires `name`, `description`, and `compatibility` fields for skill registration
- Conversational flows use numbered steps with specific directives like `ask_user_input_v0` and hard-gate warnings
- Helper scripts in `skills/<name>/scripts/` extend capabilities via the `run` tool without cluttering the skill definition
- Claude discovers skills by scanning for [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files and caches their instruction sets for runtime execution

## Frequently Asked Questions

### What file format is used to define a skill in a 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. The YAML block (enclosed by `---`) specifies the skill's machine-readable metadata, while the remaining markdown content provides the human-readable instructions that Claude follows during execution.

### Where does the plugin configuration reside in the anthropics/claude-plugins-community repository?

The plugin configuration resides in **[`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json)** at the root of each plugin folder (e.g., [`tres-finance-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json)). This JSON file contains the plugin metadata, required MCP connections, and the directory path where Claude should search for [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files.

### 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** to determine the root directory of the plugin package. It then recursively scans this directory for any files named exactly [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md). Each discovered file is parsed to register the skill with Claude's tool system using the metadata from the file's YAML header.

### Can skills execute external scripts or code?

Yes. Skills can reference helper scripts stored in a **`scripts/` subdirectory** within the individual skill folder (e.g., [`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)). Claude executes these scripts via the `run` tool, passing arguments defined in the skill's markdown instructions. This allows skills to perform complex data processing while keeping the skill definition declarative and readable.