skill-optimizer

これはレビュー時に保存された抜粋です。完全で最新の内容は外部ソースを確認してください。

---
name: skill-optimizer
description: Optimize Claude Code skills for token efficiency using progressive disclosure and content loading order. Use when optimizing skills, reducing token usage, restructuring skill content, improving skill performance, analyzing skill size, applying 500-line rule, implementing progressive disclosure, organizing reference files, optimizing YAML frontmatter, reducing context consumption, improving skill architecture, analyzing token costs, splitting large skills, or working with skill content loading. Covers Level 1 (metadata), Level 2 (instructions), Level 3 (resources) loading optimization.
---

# 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 includi