What are skills?

Learn how skills work, their structure, and the progressive disclosure system that keeps Claude’s context efficient

Skills are a powerful way to teach Claude specialized capabilities. Instead of repeatedly explaining the same workflow or pasting the same instructions, you can package knowledge into a reusable skill that Claude loads automatically when needed.

How skills work

Skills use a progressive disclosure system that balances context efficiency with access to detailed information:

1. Skills are always available

   Claude sees the name and description of all installed skills in its context. This metadata (~100 words per skill) helps Claude decide when to load a skill.

   Example from the PDF skill:

   name: pdf
   description: Use this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable.
   
2. Main instructions load on trigger

   When a skill is relevant, Claude loads the SKILL.md body containing core instructions. This is typically under 500 lines and provides the main workflow guidance.

   The PDF skill’s main instructions cover:

   • Quick reference for common tasks
   • Python library usage (pypdf, pdfplumber, reportlab)
   • Command-line tools (qpdf, pdftotext)
   • Code examples for merging, splitting, extracting tables
3. Resources load as needed

   For deeper detail, skills can bundle reference files that Claude reads only when needed:

   • references/ - Documentation loaded selectively (e.g., advanced API details)
   • scripts/ - Executable code that runs without loading into context
   • assets/ - Files used in output (templates, icons, fonts)

   The MCP builder skill uses this pattern:

   references/
   ├── mcp_best_practices.md
   ├── node_mcp_server.md
   ├── python_mcp_server.md
   └── evaluation.md
   

   Claude reads these only when implementing specific functionality.

Anatomy of a skill

Every skill follows this structure:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled resources (optional)
    ├── scripts/    - Executable code
    ├── references/ - Documentation
    └── assets/     - Templates and files

Required: SKILL.md

The only required file is SKILL.md with YAML frontmatter:

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

# My skill name

[Add your instructions here that Claude will follow when this skill is active]

## Examples
- Example usage 1
- Example usage 2

## Guidelines
- Guideline 1
- Guideline 2

Frontmatter fields:

• name - Unique identifier (lowercase, hyphens for spaces)
• description - Complete description of what the skill does and when to use it (this is the primary triggering mechanism)
• license - Optional license information
• compatibility - Optional list of required tools or dependencies

Optional: Bundled resources

Skills can include additional files:

Scripts (scripts/) - Executable code for deterministic tasks:

# scripts/extract_tables.py
import pdfplumber
import pandas as pd

def extract_all_tables(pdf_path):
    # ... implementation

Skills reference scripts in their instructions, and Claude can run them directly without loading them into context.

References (references/) - Detailed documentation:

# references/advanced_features.md

## Complex table extraction
[Detailed examples and edge cases]

Claude reads these files only when working on tasks that need the specific information.

Assets (assets/) - Files used in output:

• Templates (document templates, HTML scaffolds)
• Visual elements (logos, icons, fonts)
• Configuration files

Progressive disclosure in action

Here’s how the skill creator skill uses progressive disclosure:

Level 1 - Metadata (always in context):

name: skill-creator
description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, or run evals to test a skill.

Level 2 - Main instructions (~480 lines):

• High-level workflow for creating skills
• Interview questions to capture intent
• How to write SKILL.md
• Testing and iteration process
• When to read reference files

Level 3 - References (loaded as needed):

• references/schemas.md - JSON structures for evaluation files
• agents/grader.md - How to evaluate test outputs
• agents/comparator.md - Blind A/B comparison process
• agents/analyzer.md - Benchmark analysis guidelines

Why progressive disclosure matters

This three-level system provides key benefits:

Efficient context usage - Only load what’s needed for the current task:

• Creating a simple skill? Just the main instructions
• Running complex evaluations? Load the grader and analyzer references
• Optimizing skill descriptions? Load the description optimizer docs

Unlimited specialized knowledge - Scripts and large reference files don’t count against context limits when not loaded.

Clear organization - The structure makes it obvious where to find information:

• Quick patterns? Check the main SKILL.md
• Detailed edge cases? Look in references/
• Reusable automation? Run scripts/

Faster execution - Scripts run without being read, saving both time and context.

Skill triggering

Claude decides whether to use a skill based on the description field. Make descriptions specific:

Good example

---
name: pdf
description: Use this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.
---

---
name: pdf
description: Work with PDF documents
---

Claude tends to “undertrigger” skills - to not use them when they’d be useful. Make descriptions slightly “pushy” by listing multiple contexts where the skill applies.

Real-world example: MCP builder

The MCP builder skill shows progressive disclosure at scale:

Main SKILL.md (~237 lines):

• Four-phase workflow (research, implementation, review, evaluation)
• When to load each reference file
• High-level best practices
• Links to detailed guides

References loaded selectively:

1. mcp_best_practices.md - Universal MCP guidelines (loaded during Phase 1)
2. node_mcp_server.md - TypeScript patterns (loaded only if using TypeScript)
3. python_mcp_server.md - Python patterns (loaded only if using Python)
4. evaluation.md - Testing guidelines (loaded only during Phase 4)

This structure means:

• A Python developer never loads the TypeScript guide
• Implementation phase doesn’t load evaluation docs
• Context stays focused on the current phase

Key principles

Keep SKILL.md under 500 lines - If approaching this limit, move detailed content to reference files with clear pointers about when to read them.

When organizing large skills:

1. Main instructions should be workflows, not encyclopedias - Guide Claude through the process and tell it where to find details

2. Reference files should be self-contained - Each reference should cover one topic completely so Claude can read just that file

3. Scripts should be reusable - Write scripts that multiple skills could use, not one-off implementations

4. Group by variant, not by type - For skills supporting multiple frameworks:

   cloud-deploy/
   ├── SKILL.md (selection logic)
   └── references/
       ├── aws.md
       ├── gcp.md
       └── azure.md
   

   Claude reads only the relevant cloud provider’s file.

Example: Building a brand guidelines skill

Here’s a simple but complete skill:

---
name: brand-guidelines
description: Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
---

# Anthropic brand styling

## Colors

**Main colors:**
- Dark: `#141413` - Primary text and dark backgrounds
- Light: `#faf9f5` - Light backgrounds and text on dark
- Mid Gray: `#b0aea5` - Secondary elements

**Accent colors:**
- Orange: `#d97757` - Primary accent
- Blue: `#6a9bcc` - Secondary accent
- Green: `#788c5d` - Tertiary accent

## Typography

- **Headings**: Poppins (with Arial fallback)
- **Body text**: Lora (with Georgia fallback)

## Usage

Apply these colors and fonts to:
- PowerPoint presentations
- PDF reports
- HTML artifacts
- Data visualizations

This skill:

• Has clear triggering in the description
• Provides actionable guidelines in ~30 lines
• Needs no bundled resources (colors and fonts are the only data)
• Can be used immediately

Next steps

Install skills

Set up skills in Claude Code, Claude.ai, or the API

Create your first skill

Use the template to build a custom skill