Claude Plugin Skill Files Format: The Complete Developer Guide

Claude plugin skill files are Markdown documents with mandatory YAML front-matter headers that define metadata, followed by standard Markdown content describing the workflow.

The anthropics/claude-plugins-community repository establishes a standardized format for extending Claude's capabilities through reusable skills. Each skill is declared in a dedicated SKILL.md file that combines machine-readable configuration with human-readable documentation, allowing the Claude runtime to parse instructions while maintaining clear specifications for developers.

Required File Structure

Every skill file must adhere to a strict two-part structure. The file begins with a YAML front-matter block enclosed by triple dashes (---), followed by free-form Markdown content that describes the skill's logic and user interactions.

This hybrid format ensures that Claude can extract essential metadata during plugin loading while preserving rich documentation, code examples, and step-by-step workflows for end users.

YAML Front-Matter Header

The header section is mandatory and must contain at least the name and description keys. The block opens and closes with --- delimiters.

YAML Key	Requirement	Description
name	Required	A short, kebab-case identifier (e.g., tres-wallets-upload)
description	Required	A concise, plain-text summary of the skill's purpose
compatibility	Optional	Runtime requirements or external service dependencies

The name field serves as the unique identifier referenced by the plugin manifest, while the description appears in Claude's interface to help users understand the skill's function.

Markdown Body Content

After the closing --- delimiter, the remainder of the file uses standard Markdown syntax. The body typically contains:

• Section headings (e.g., ## Step 0 — Initialize, ## ON-CHAIN FLOW) to structure multi-step workflows

• Code fences for JSON prompts, GraphQL queries, shell commands, or configuration examples

• Tables to display data schemas or preview expected inputs

• Bullet lists and blockquotes for validation rules, warnings, or user instructions

Complete Skill File Example

A minimal skill file located at my-skill/SKILL.md demonstrates the required structure:

---
name: my-skill
description: >
  Demonstrates the basic layout of a Claude plugin skill file.
compatibility: "Requires no external services"
---

# My Skill

This skill simply asks the user for a string and echoes it back.

## Step 0 — Ask for Input

```json
{
  "question": "Enter a short message:",
  "type": "text"
}

Step 1 — Echo the Input

Claude will respond with:

You said: <user-input>

A production example can be found in the repository at [`tres-finance-plugin/skills/tres-wallets-upload/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-wallets-upload/SKILL.md). This file implements the `tres-wallets-upload` skill with extensive step definitions, validation rules, and embedded GraphQL queries for the Tres Finance MCP integration.

## Skill Registration and Manifest Files

Individual [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files are not automatically discovered; they must be explicitly referenced by the plugin's central manifest. The [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) file located in the plugin root contains an array of skill definitions pointing to each [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) location.

For example, the `quickdesign` plugin references its skills through its manifest at [`quickdesign/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json). Developers may also include an optional [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) file to provide additional metadata such as icons, categories, and display descriptions for the Claude marketplace.

## Summary

- Claude plugin skill files use a **Markdown format with YAML front-matter** requiring `name` and `description` keys.
- The YAML header is delimited by `---` and must use kebab-case identifiers for the `name` field.
- The Markdown body supports headings, code blocks, tables, and lists to document workflows.
- Skills are defined in [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files within skill subdirectories, then registered via [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json).
- Optional `compatibility` fields declare external service dependencies like MCP servers.

## Frequently Asked Questions

### What file extension must Claude plugin skill files use?

Claude plugin skill files must be named exactly [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) with the Markdown extension. The Claude runtime specifically looks for this filename when loading skills referenced in the plugin manifest, regardless of the subdirectory structure within `skills/`.

### Is the compatibility field in the YAML header mandatory?

No, the `compatibility` field is optional. If omitted, Claude assumes the skill has no external dependencies. When present, this field should contain a plain-text string describing required runtimes or connected services, such as "Requires TRES Finance MCP connected."

### How does Claude discover skill files in a plugin?

Claude does not automatically scan for skill files. Each [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) must be explicitly listed in the [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) manifest file located in the plugin root. This JSON file contains the skill registry that tells Claude which files to load and parse.

### Can I include code blocks in the Markdown body of a skill file?

Yes, the Markdown body supports fenced code blocks using triple backticks with language specifiers. These are commonly used to define JSON prompt schemas, GraphQL queries, shell commands, or example outputs that Claude will use when executing the skill workflow.

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