> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/anthropics/skills/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
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:
```yaml theme={null}
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.
```
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
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:
```markdown theme={null}
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:
```markdown theme={null}
---
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:
```python theme={null}
# 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:
```markdown theme={null}
# 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):**
```yaml theme={null}
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:
```yaml Good example theme={null}
---
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.
---
```
```yaml Too vague theme={null}
---
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:
```markdown theme={null}
---
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
Set up skills in Claude Code, Claude.ai, or the API
Use the template to build a custom skill