tools-only Progressive Disclosure Patterns
Skills use a 3-level loading system to manage context efficiently.
3-Level Loading System
- Metadata (name + description) - Always in context (~100 words)
- SKILL.md body - When Skill is triggered (<5k words, recommended 500 lines)
- Bundled resources - When Claude needs them (unlimited - scripts can be executed without loading into context)
Core Principle
When a Skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guide in SKILL.md. Move variation-specific details to separate reference files.
Pattern 1: High-level Guide with References
When to Use: When there are multiple related features
Example Structure:
# PDF Processing
## Quick start
Extract text with pdfplumber:
[code example]
## Advanced features
- **Form filling**: See [FORMS.md](references/FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](references/REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](references/EXAMPLES.md) for common patterns
Claude loads FORMS.md, REFERENCE.md, EXAMPLES.md only when needed.
Pattern 2: Domain-specific Organization
When to Use: When a large domain has distinct sub-domains
Example Structure (Skill with multiple domains):
bigquery-skill/
├── SKILL.md (overview and navigation)
└── references/
├── finance.md (revenue, billing metrics)
├── sales.md (opportunities, pipeline)
├── product.md (API usage, features)
└── marketing.md (campaigns, attribution)
When a user asks about sales metrics, Claude reads only sales.md.
Example Structure (Skill supporting multiple frameworks/variations):
cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
├── aws.md (AWS deployment patterns)
├── gcp.md (GCP deployment patterns)
└── azure.md (Azure deployment patterns)
When a user selects AWS, Claude reads only aws.md.
Pattern 3: Conditional Details
When to Use: When advanced features are occasionally needed
Example Structure:
# DOCX Processing
## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](references/DOCX-JS.md).
## Editing documents
For simple edits, modify the XML directly.
**For tracked changes**: See [REDLINING.md](references/REDLINING.md)
**For OOXML details**: See [OOXML.md](references/OOXML.md)
Claude reads the relevant reference only when the user needs that feature.
Important Guidelines
Avoid deep nesting: References should maintain 1-level depth from SKILL.md. All reference files should be directly linked from SKILL.md.
Structure long reference files: Files over 100 lines should include a table of contents at the top so Claude can see the full scope when previewing.
Avoid duplication: Information should be in either SKILL.md or references files, not both.
Practical Examples
PDF Editor Skill
pdf-editor/
├── SKILL.md (Quick start + navigation)
└── references/
├── FORMS.md (form filling guide)
├── REFERENCE.md (API reference)
└── EXAMPLES.md (common patterns)
BigQuery Skill
bigquery-skill/
├── SKILL.md (overview + domain navigation)
└── references/
├── finance.md
├── sales.md
├── product.md
└── marketing.md