Claude Skills Documentation: Official Reference & API Docs

SKILL.md File Format

Every skill requires a SKILL.md file. It has two parts: YAML frontmatter that tells Claude when to use the skill, and Markdown content with instructions Claude follows when invoked.

Frontmatter (Required)

The frontmatter sits between --- markers at the top of SKILL.md. Two fields are required:

--- name: my-skill-name description: A clear description of what this skill does and when to use it ---

Writing effective descriptions:

The description field is the most important part of frontmatter — it's the only content Claude sees before deciding whether to load the full skill. Include:

• What the skill does
• When Claude should use it
• Trigger phrases that users might say

--- name: explain-code description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?" ---

Source: Claude Code Docs — Extend Claude with skills; Skill authoring best practices — Claude API Docs

Markdown Content (Required)

After the frontmatter, write instructions in Markdown. This is the prompt Claude receives when the skill is invoked.

markdown

--- name: explain-code description: Explains code with visual diagrams and analogies. --- When explaining code, always include: 1. **Start with an analogy**: Compare the code to something from everyday life 2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships 3. **Walk through the code**: Explain step-by-step what happens 4. **Highlight a gotcha**: What's a common mistake or misconception?

Content guidelines:

• Keep SKILL.md focused on core instructions — under 500 lines to minimize context bloat
• Move detailed content to separate files in references/ or scripts/
• Reference external files explicitly so Claude knows they exist and when to read them
• Include concrete examples, not abstract instructions
• Write for another Claude instance, not a human — include information that would be beneficial and non-obvious to Claude

Source: anthropics/skills GitHub — skill-creator/SKILL.md; Skill authoring best practices — Claude API Docs

Skill Directory Structure

A skill is a folder. The SKILL.md file is required; everything else is optional.

my-skill/ ├── SKILL.md # Required — instructions + YAML frontmatter ├── scripts/ # Optional — executable code (Python, Bash, etc.) │ ├── validate.py │ └── generate.sh ├── references/ # Optional — documentation loaded into context as needed │ ├── workflows.md │ └── style-guide.md ├── assets/ # Optional — files used in output (templates, icons, fonts) │ ├── template.html │ └── logo.png └── LICENSE.txt # Optional — license file

Three content types and their loading behavior

This three-level progressive disclosure system means:

• Installing many skills has near-zero context cost
• Only relevant content loads when needed
• Scripts execute efficiently without polluting the context window

Source: Agent Skills Overview — Claude API Docs; Anthropic Engineering Blog — Equipping agents for the real world

Claude API — Skills Endpoints

Skills are available via the Claude Messages API with the Code Execution Tool. Both pre-built and custom skills work identically.

Prerequisites

Using Skills via the API requires three beta headers:

code-execution-2025-05-22 # Code execution tool support extended-cache-ttl-2025-04-11 # Optional extended prompt cache TTL interleaved-thinking-2025-05-14 # Optional interleaved thinking

Using Pre-Built Skills

Reference a pre-built skill by its skill_id in the container parameter:

{ "model": "claude-sonnet-4-5-20250929", "max_tokens": 16384, "tools": [{ "type": "code_execution_20250522" }], "container": { "skill_ids": ["pptx"] }, "messages": [ { "role": "user", "content": "Create a 5-slide presentation about Q4 results" } ] }

Available pre-built skill_id values:

Using Custom Skills

Create custom skills via the /v1/skills endpoint, then reference them by skill_id:

{ "container": { "skill_ids": ["pptx", "your-custom-skill-id"] } }

The /v1/skills endpoint supports:

• Creating new custom skills
• Viewing existing skills
• Upgrading skill versions
• Programmatic skill management

Custom skills can also be managed via the Claude Console.

Source: Agent Skills Overview — Claude API Docs; Skills API Quickstart — Claude API Docs

Skills Across Platforms

Skills use the same format everywhere but install differently depending on the platform.

Claude.ai

Claude Code

Claude API

Agent Skills Open Standard

Source: Claude Help Center — What are Skills?; Claude Code Docs — Extend Claude with skills; Agent Skills Overview — Claude API Docs

Skill Authoring Best Practices

Guidance from Anthropic's official documentation and the skill-creator reference implementation.

Description Writing

SKILL.md Content

Progressive Disclosure

Testing

Source: Skill authoring best practices — Claude API Docs; anthropics/skills GitHub — skill-creator/SKILL.md

Official Documentation Links

A curated index of every official Anthropic resource related to Claude Skills.