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

Skills in Claude plugins are defined via markdown files named SKILL.md that contain YAML front‑matter metadata and step‑by‑step conversational instructions, discovered through a top‑level 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 manifest serves as the entry point. Located at .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 files contain the actual skill logic. These markdown documents reside in subdirectories under the skills folder (e.g., 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 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:

---
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 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 for any file named exactly 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:

# 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 and follows the steps defined there.

Minimal SKILL.md Template

Create a new skill by following this skeleton structure:

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

### 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 files containing YAML front‑matter and markdown instructions
• The 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 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. 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 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 manifest for any file named 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.

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