skill-optimizer

What this skill does

# Skill Optimizer

## Purpose

Optimize existing Claude Code skills to minimize token consumption by leveraging the three-level content loading architecture and progressive disclosure patterns.

## When to Use

Use this skill when:
- Analyzing existing skills for optimization opportunities
- Skills are too large (approaching or exceeding 500 lines)
- Need to reduce context consumption
- Restructuring skills for progressive disclosure
- Converting monolithic skills to multi-file architecture
- Optimizing YAML frontmatter for better discovery
- Improving skill performance and load times
- Auditing skills for token efficiency
- Creating new skills with optimization in mind

---

## Content Loading Architecture

### Three-Level Loading System

**Level 1: Metadata (Always Loaded - ~100 tokens/skill)**
- YAML frontmatter in SKILL.md
- Loaded at startup into system prompt
- Enables skill discovery without context overhead
- **Optimization Target**: Description field (max 1024 chars)

**Level 2: Instructions (Loaded When Triggered - <5,000 tokens)**
- Main SKILL.md content
- Loads dynamically when skill is relevant
- Contains workflows, best practices, guidance
- **Optimization Target**: Keep under 500 lines

**Level 3: Resources (Loaded As Needed - Variable)**
- Additional markdown files (REFERENCE.md, EXAMPLES.md, etc.)
- Code scripts in scripts/ directory
- Templates, schemas, documentation
- **Optimization Target**: No penalty until accessed

### Key Principle

**"Files don't consume context until accessed"** - Bundle comprehensive documentation in reference files without context penalty.

---

## Quick Optimization Workflow

### 1. Analyze Current State

**Check skill size:**
```bash
wc -l .claude/skills/skill-name/SKILL.md
```

**Identify optimization opportunities:**
- [ ] SKILL.md > 500 lines?
- [ ] Detailed API docs in main file?
- [ ] Extensive examples in main file?
- [ ] Long reference tables or schemas?
- [ ] Code snippets that could be scripts?
- [ ] Multiple distinct topics/sections?

### 2. Apply 500-Line Rule

**If SKILL.md > 500 lines:**

✅ **Keep in main file:**
- Purpose and when to use
- Quick start / common workflows
- Critical best practices
- Brief examples (5-10 lines)
- Cross-references to detailed files

❌ **Move to reference files:**
- Comprehensive API documentation
- Extensive code examples (>20 lines)
- Detailed troubleshooting guides
- Pattern libraries
- Schema definitions
- Long reference tables

### 3. Structure 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**

### 4. Optimize YAML Frontmatter

**Description optimization (max 1024 chars):**

✅ **Include:**
- All trigger keywords and phrases
- Use cases and scenarios
- File types and technologies
- Common action verbs
- Related concepts

❌ **Avoid:**
- Generic descriptions
- Missing key terms
- Overly verbose explanations

**Example:**
```yaml
---
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.
---
```

### 5. Implement Progressive Disclosure

**Pattern:**
```markdown
## 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)
```

---

## Optimization Patterns Summary

### Pattern 1: Extract API Documentation

**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](REFERENCE.md#pattern-1-extract-api-documentation)

### Pattern 2: Extract Pattern Libraries

**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](REFERENCE.md#pattern-2-extract-pattern-libraries)

### Pattern 3: Extract Troubleshooting

**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](REFERENCE.md#pattern-3-extract-troubleshooting)

### Pattern 4: Convert Code to Scripts

**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](REFERENCE.md#pattern-4-convert-code-to-scripts)

---

## Common Anti-Patterns

Avoid these common mistakes when creating or optimizing skills:

❌ **Anti-Pattern 1: Monolithic Skills**
- Single SKILL.md with 1000+ lines
- Solution: Split into main + reference files

❌ **Anti-Pattern 2: Incomplete References**
- Reference files exist but not linked
- Solution: Link all reference files from SKILL.md

❌ **Anti-Pattern 3: Nested References**
- References pointing to other references (>1 level)
- Solution: Keep hierarchy flat (max 1 level)

❌ **Anti-Pattern 4: Sparse Frontmatter**
- Minimal YAML description missing keywords
- Solution: Rich description with all triggers

❌ **Anti-Pattern 5: Code as Documentation**
- 100+ line scripts embedded in markdown
- Solution: Move to scripts/ directory

**For detailed anti-patterns and solutions**: [REFERENCE.md](REFERENCE.md#common-anti-patterns)

---

## Migration Workflow

### Quick Migration Steps

**Phase 1: Discovery**
```bash
# 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**
- Design file hierarchy (SKILL.md + reference files)
- Plan content distribution
- Identify scripts to extract

**Phase 3: Implementation**
```bash
# 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**
- Trim remaining content
- Optimize frontmatter with trigger keywords
- Add navigation aids (table of contents)

**Phase 5: Validation**
```bash
# 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](REFERENCE.md#complete-migration-workflow)

---

## Advanced Techniques

Quick reference to advanced optimization strategies:

**Technique 1: Conditional Content Loading**
- Structure content so advanced sections load only when needed
- Benefits: Most users don't load advanced content

**Technique 2: Layered Examples**
- Progressive complexity: minimal → production → enterprise
- Benefits: Beginners see simple examples, advanced users access complex ones

**Technique 3: Executable Documentation**
- Scripts that both execute and document
- Benefits: Zero token cost, self-documenting output