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

Skills in a Claude plugin are defined via markdown files named 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 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. This file tells Claude to look for 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, 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 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 file contain a YAML block enclosed by triple dashes. This block registers the skill with Claude's system:

---
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 invokes Python scripts to parse uploaded XLSX files:

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 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. For every file named exactly 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:

# 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 and initiates the wallet-upload flow defined in the steps.

Minimal skill template

Below is a skeleton structure for creating a new skill:

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

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.

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