skill-optimizer

# 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