Optimize Claude Code skills for token efficiency using progressive disclosure and content loading order.
Optimize existing Claude Code skills to minimize token consumption by leveraging the three-level content loading architecture and progressive disclosure patterns.
Use this skill when:
Level 1: Metadata (Always Loaded - ~100 tokens/skill)
Level 2: Instructions (Loaded When Triggered - <5,000 tokens)
Level 3: Resources (Loaded As Needed - Variable)
"Files don't consume context until accessed" - Bundle comprehensive documentation in reference files without context penalty.
Check skill size:
wc -l .claude/skills/skill-name/SKILL.md
Identify optimization opportunities:
If SKILL.md > 500 lines:
✅ Keep in main file:
❌ Move to reference files:
Create organized reference hierarchy:
skill-name/
├── SKILL.md # <500 lines, workflows & quick ref
├── REFERENCE.md # Comprehensive documentation
├── EXAMPLES.md # Detailed code examples
├── PATTERNS.md # Pattern library
├── TROUBLESHOOTING.md # Debug guide
└── scripts/ # Executable utilities
└── helper.sh
Add table of contents to files >100 lines
Description optimization (max 1024 chars):
✅ Include:
❌ Avoid:
Example:
---
name: database-development
description: Database development guidance for PostgreSQL including schema design, migrations, RLS policies, indexing strategies, privacy-preserving patterns, query optimization, and Prisma ORM. Use when working with tables, columns, indexes, migrations, RLS, Row-Level Security, database schema, SQL queries, Prisma schema, database optimization, privacy architecture, or PostgreSQL best practices.
---
Pattern:
## Topic Overview
Brief explanation (2-3 sentences).
**Key Points:**
- Important consideration 1
- Important consideration 2
**For detailed information**: [REFERENCE.md](REFERENCE.md#topic-details)
**Quick Example:**
\`\`\`typescript
// Minimal working example (5-10 lines)
\`\`\`
**For more examples**: [EXAMPLES.md](EXAMPLES.md#topic-examples)
Strategy: Move detailed API docs to REFERENCE.md
Before: 80+ lines of API documentation in SKILL.md After: 10-line summary with link to complete docs Savings: ~70 lines (~1,400 tokens)
For complete pattern details: REFERENCE.md
Strategy: Move code patterns to PATTERNS.md
Before: 200+ lines of pattern code in SKILL.md After: 18-line summary with quick example Savings: ~182 lines (~3,640 tokens)
For complete pattern details: REFERENCE.md
Strategy: Move debug guides to TROUBLESHOOTING.md
Before: 300+ lines of troubleshooting in SKILL.md After: 18-line summary with quick diagnostics Savings: ~282 lines (~5,640 tokens)
For complete pattern details: REFERENCE.md
Strategy: Move executable code to scripts/ directory
Before: 55+ lines of bash script in SKILL.md After: 7-line reference to executable script Savings: ~48 lines (~960 tokens) + script code never enters context
For complete pattern details: REFERENCE.md
Avoid these common mistakes when creating or optimizing skills:
❌ Anti-Pattern 1: Monolithic Skills
❌ Anti-Pattern 2: Incomplete References
❌ Anti-Pattern 3: Nested References
❌ Anti-Pattern 4: Sparse Frontmatter
❌ Anti-Pattern 5: Code as Documentation
For detailed anti-patterns and solutions: REFERENCE.md
Phase 1: Discovery
# Check skill size
wc -l .claude/skills/skill-name/SKILL.md
# Identify sections to extract
grep "^##" .claude/skills/skill-name/SKILL.md
Phase 2: Planning
Phase 3: Implementation
# Create reference files
touch REFERENCE.md EXAMPLES.md
mkdir -p scripts
# Extract content systematically
# 1. Copy section to reference file
# 2. Replace in SKILL.md with summary + link
# 3. Verify link works
# 4. Remove detailed content from SKILL.md
Phase 4: Optimization
Phase 5: Validation
# Verify under 500 lines
wc -l .claude/skills/skill-name/SKILL.md
# Test links work
grep -o '\[.*\](.*\.md#.*)' SKILL.md
For complete migration workflow: REFERENCE.md
Quick reference to advanced optimization strategies:
Technique 1: Conditional Content Loading
Technique 2: Layered Examples
Technique 3: Executable Documentation
Technique 4: Tabular Compression
Technique 5: Smart Chunking
For detailed advanced techniques: REFERENCE.md
When optimizing a skill, verify:
Quick estimate:
lines=$(wc -l < SKILL.md)
tokens=$((lines * 20)) # Conservative: 20 tokens/line
echo "Estimated tokens: ~$tokens"
Target: Keep SKILL.md under 10,000 tokens (~500 lines)
# Calculate savings
BEFORE=850 # lines before optimization
AFTER=420 # lines after optimization
SAVINGS=$((BEFORE - AFTER))
TOKEN_SAVINGS=$((SAVINGS * 20))
echo "Reduced by $SAVINGS lines"
echo "Estimated token savings: ~$TOKEN_SAVINGS tokens"
For detailed measurement methods: REFERENCE.md
✅ DO:
❌ DON'T:
File size limits:
Optimization priority:
Common extractions:
Typical token savings:
For comprehensive optimization patterns and detailed workflows: REFERENCE.md
Before optimization:
skill-example/
└── SKILL.md (850 lines, ~17,000 tokens)
After optimization:
skill-example/
├── SKILL.md (420 lines, ~8,400 tokens)
├── REFERENCE.md (350 lines, loaded on-demand)
├── EXAMPLES.md (180 lines, loaded on-demand)
└── scripts/
├── validate.sh (code never enters context)
└── setup.sh (code never enters context)
Result: 50% token reduction on initial load, comprehensive docs still available on-demand
Next Steps:
wc -l .claude/skills/*/SKILL.mdFor detailed guidance: See REFERENCE.md for complete optimization patterns, anti-patterns, migration workflows, and advanced techniques.