What are skills?

​

How skills work

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.

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

​

Anatomy of a skill

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

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

• 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

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

def extract_all_tables(pdf_path):
    # ... implementation

# references/advanced_features.md

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

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

​

Progressive disclosure in action

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.

• 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

• 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

• 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

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

​

Skill triggering

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

​

Real-world example: MCP builder

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

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)

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

​

Key principles

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

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

• 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