8.1 KiB
Progressive Disclosure
Guide to properly structuring information across the three levels of skill loading.
The Three Levels
Skills use progressive disclosure to minimize context usage while maximizing discoverability.
Level 1: Metadata (Always Loaded)
What: YAML frontmatter in SKILL.md When: Always (loaded at startup) Token cost: ~100 tokens per skill Purpose: Skill discovery and triggering
---
name: skill-name
description: What the skill does and when to use it. Be comprehensive - this is how Claude discovers your skill.
---
Best practices:
- Description should answer: "What does this do?" and "When should I use it?"
- Include trigger keywords users might mention
- Be specific but concise (max 1024 characters)
- No implementation details (those go in Level 2/3)
Example (good):
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
Example (bad):
description: PDF tool. Uses pdfplumber library with various configuration options for text extraction, table parsing, and form filling operations on PDF documents.
Level 2: Instructions (Loaded When Triggered)
What: The markdown body of SKILL.md When: When Claude triggers the skill Token cost: Should be under 5k tokens Purpose: Core instructions and workflow guidance
What belongs here:
- Quick start / getting started
- Core workflow steps
- Essential examples (minimal and representative)
- Links to Level 3 resources
- Common use cases
- Key concepts
What doesn't belong here:
- Detailed API documentation → references/api-reference.md
- Extensive examples → references/examples.md
- Configuration details → references/configuration.md
- Troubleshooting guides → references/troubleshooting.md
- Long reference material → references/
Structure:
# Skill Name
## Quick Start
[Minimal getting started example]
## Core Workflow
[Essential steps for main use case]
## Common Tasks
[2-3 most common scenarios with brief examples]
## Advanced Usage
See [advanced-usage.md](references/advanced-usage.md)
Keep it lean:
- ❌ Walls of text
- ❌ Every possible parameter
- ❌ Exhaustive examples
- ✅ Core workflow
- ✅ Minimal examples
- ✅ Links to references
Level 3: Resources (Loaded As Needed)
What: Files in references/, scripts/, assets/ When: When Claude determines they're needed Token cost: Varies (can be large) Purpose: Detailed documentation, code, assets
Proper organization:
skill-name/
├── SKILL.md (Level 2: Core instructions)
└── references/ (Level 3: Detailed resources)
├── api-reference.md (Complete API docs)
├── examples.md (Comprehensive examples)
├── configuration.md (All config options)
├── troubleshooting.md (Common issues)
└── advanced-usage.md (Advanced patterns)
When to create reference files:
- Content > 1000 words → separate file
- Detailed specifications → separate file
- Comprehensive examples → separate file
- Reference tables/lists → separate file
- Specialized workflows → separate file
How to link from SKILL.md:
For complete API documentation, see [api-reference.md](references/api-reference.md).
For all configuration options, see [configuration.md](references/configuration.md).
Anti-Patterns
❌ Everything in SKILL.md
# Skill Name
## Introduction
[500 words of background...]
## Complete API Reference
[5000 words of API docs...]
## Configuration
[1000 words of config options...]
## Examples
[50 examples...]
## Troubleshooting
[30 common issues...]
Problem: Loads 10k+ tokens every time skill is triggered, even for simple tasks.
Fix: Move sections to references/:
- api-reference.md
- configuration.md
- examples.md
- troubleshooting.md
Keep only quick start and core workflow in SKILL.md.
❌ Duplicate Content
SKILL.md:
## Authentication
Set API_KEY environment variable.
## API Reference
Full authentication documentation:
- Set API_KEY environment variable
- Obtain key from dashboard
- Key format: 32 hex characters
- Rotation: every 90 days
references/api-reference.md:
## Authentication
Set API_KEY environment variable.
Obtain key from dashboard...
[same content repeated]
Problem: Same information in multiple places. Wastes tokens and creates maintenance burden.
Fix: Put detailed info in ONE place (references/), link from SKILL.md.
SKILL.md:
## Quick Start
Set `API_KEY` environment variable:
```bash
export API_KEY="your-key-here"
For authentication details, see api-reference.md.
---
### ❌ Unclear Load Boundaries
```markdown
# Skill Name
Some stuff in SKILL.md...
[Inline 2000 words of detailed configuration]
...more stuff...
For additional examples, see examples.md.
Problem: Heavy content inline, light content in references. Backwards from ideal.
Fix: Keep SKILL.md lean, move heavy content to references.
Implementation Guide
Audit Existing Skill
-
Measure SKILL.md size:
wc -w skill-name/SKILL.mdTarget: Under 1500 words (~5k tokens)
-
Identify heavy sections:
- Complete API docs
- Exhaustive examples
- Configuration tables
- Troubleshooting guides
-
Extract to references:
mkdir -p skill-name/references # Move heavy sections to focused files -
Update links: Replace inline content with links to references/
Create New Skill
-
Start with metadata:
--- name: skill-name description: Clear description with trigger keywords --- -
Write lean SKILL.md:
- Quick start (1 example)
- Core workflow (essential steps)
- Links to references (for depth)
-
Create references as needed:
- Only when content > 1000 words
- One focused topic per file
- Clear file names
-
Link properly:
For [topic], see [references/topic.md](references/topic.md).
Verification Checklist
Progressive disclosure audit:
- SKILL.md under 1500 words (~5k tokens)
- Metadata (frontmatter) is concise and comprehensive
- SKILL.md contains only core workflow and essential examples
- Detailed content moved to references/
- No duplicate content between SKILL.md and references/
- Links from SKILL.md to references/ are clear and resolve correctly
- Reference file names indicate content
- Each reference file has one focused purpose
Progressive Disclosure in Practice
Example: tmux Skill
Level 1 (Metadata - Always loaded):
description: Remote control tmux sessions for interactive CLIs (python, gdb, etc.)
Level 2 (SKILL.md - Loaded when triggered):
# tmux Skill
## Quick Start
1. Create session: `create-session.sh -n my-session --python`
2. Send command: `safe-send.sh -s my-session -c "print('hello')"`
3. Wait for output: `wait-for-text.sh -s my-session -p ">>>"`
For session registry details, see [session-registry.md](references/session-registry.md).
Level 3 (References - Loaded as needed):
references/session-registry.md(530+ lines of comprehensive registry docs)- Only loaded when Claude needs registry details
Result:
- Metadata: ~30 tokens (always)
- Core instructions: ~1k tokens (when triggered)
- Registry docs: ~2k tokens (only when needed for registry-specific questions)
Total context impact: 30 tokens idle, 1k tokens typical use, 3k tokens for deep dives.
Without progressive disclosure: 3k+ tokens always loaded.
Summary
Three levels, three loading times:
- Metadata (always): Name + description for discovery
- Instructions (when triggered): Core workflow in SKILL.md
- Resources (as needed): Detailed docs in references/
Key principle: Information loads when needed, not before.
Target metrics:
- Metadata: ~100 tokens
- SKILL.md: <5k tokens (preferably <3k)
- References: No limit (loaded selectively)