Skills Optimizer
Audit skills for token efficiency and progressive disclosure compliance.
What This Skill Does
| Operation |
Script |
Description |
| Analyze Skill |
analyze-skill.sh |
Audit single skill's token footprint |
| Audit All |
audit-all-skills.sh |
Batch audit entire skills directory |
| Validate |
validate-skill.sh |
Check structure and compliance |
Quick Start
Audit a Single Skill
./scripts/analyze-skill.sh ~/.claude/skills/my-skill
# Output: Token count, violations, recommendations
Audit All Skills
./scripts/audit-all-skills.sh ~/.claude/skills
# Generates: audit-report.json with per-skill scores
Validation Checklist
The 3-Level Disclosure Model
| Level |
Target |
Loaded When |
Contains |
| L1: Metadata |
~200 chars |
Startup (all skills) |
name, description, triggers |
| L2: SKILL.md |
<500 lines |
Skill triggered |
Quick start, workflow overview |
| L3: Nested docs |
Variable |
Explicitly accessed |
API refs, examples, guides |
Optimization Workflow
- Measure:
wc -w SKILL.md (target: <2000 words)
- Identify violations (see table below)
- Apply fixes
- Validate:
./scripts/validate-skill.sh
Common Violations
| Violation |
Detection |
Fix |
| Bloated description |
>1024 chars |
Trim, front-load keywords |
| Voodoo constants |
Explains PDF/JSON/API |
Delete (Claude knows) |
| Inline code dumps |
>50 line blocks |
Move to scripts/ |
| Deep nesting |
A→B→C chains |
Flatten to one level |
Router Skill Checks (R001-R005)
Automatically detected for skills mentioning "hub", "router", or "routes to...skills":
| Check |
Description |
Severity |
| R001 |
Quick Reference table with Risk column |
Warning |
| R002 |
Risk Legend present |
Warning |
| R003 |
Negative Triggers documented |
Warning |
| R004 |
Disambiguation examples |
Warning |
| R005 |
Context awareness (pronoun resolution) |
Info |
Risk Level Checks (K001-K003)
Applied to skills with scripts/ directory:
| Check |
Description |
Severity |
| K001 |
Destructive scripts have ⚠️ indicators |
Warning |
| K002 |
Bulk operations marked as ⚠️⚠️ |
Warning |
| K003 |
High-risk ops document --dry-run |
Warning |
Risk Level Reference
| Risk |
Symbol |
Operations |
Required Safeguards |
| Safe |
- |
search, list, get, export |
None |
| Destructive |
⚠️ |
create, update, delete |
Confirm |
| High-risk |
⚠️⚠️ |
bulk ops, admin changes |
Confirm + dry-run |
Audit Report Format
{
"skill": "my-skill",
"tokenFootprint": { "level1": 180, "level2": 3200, "level3": 15000 },
"violations": [...],
"score": 72,
"grade": "C"
}
Related Documentation
- Disclosure Level Criteria
- Token Counting Guide
- Naming Conventions
- Validation Rules
1---2name: skills-optimizer3description: Audit and optimize skills for token efficiency and progressive disclosure compliance. Use when user wants to "analyze skill tokens", "audit skills", "optimize skill size", "check token efficiency", or "validate progressive disclosure".4---56# Skills Optimizer78Audit skills for token efficiency and progressive disclosure compliance.910## What This Skill Does1112| Operation | Script | Description |13|-----------|--------|-------------|14| Analyze Skill | `analyze-skill.sh` | Audit single skill's token footprint |15| Audit All | `audit-all-skills.sh` | Batch audit entire skills directory |16| Validate | `validate-skill.sh` | Check structure and compliance |1718---1920## Quick Start2122### Audit a Single Skill2324```bash25./scripts/analyze-skill.sh ~/.claude/skills/my-skill26# Output: Token count, violations, recommendations27```2829### Audit All Skills3031```bash32./scripts/audit-all-skills.sh ~/.claude/skills33# Generates: audit-report.json with per-skill scores34```3536### Validation Checklist3738- [ ] **L1**: Description < 1024 chars, includes triggers39- [ ] **L2**: SKILL.md < 500 lines, navigation guide40- [ ] **L3+**: Details in separate files41- [ ] **No deep nesting**: One level from SKILL.md42- [ ] **No voodoo constants**: No explaining what Claude knows4344---4546## The 3-Level Disclosure Model4748| Level | Target | Loaded When | Contains |49|-------|--------|-------------|----------|50| L1: Metadata | ~200 chars | Startup (all skills) | name, description, triggers |51| L2: SKILL.md | <500 lines | Skill triggered | Quick start, workflow overview |52| L3: Nested docs | Variable | Explicitly accessed | API refs, examples, guides |5354---5556## Optimization Workflow57581. **Measure**: `wc -w SKILL.md` (target: <2000 words)592. **Identify violations** (see table below)603. **Apply fixes**614. **Validate**: `./scripts/validate-skill.sh`6263### Common Violations6465| Violation | Detection | Fix |66|-----------|-----------|-----|67| Bloated description | >1024 chars | Trim, front-load keywords |68| Voodoo constants | Explains PDF/JSON/API | Delete (Claude knows) |69| Inline code dumps | >50 line blocks | Move to `scripts/` |70| Deep nesting | A→B→C chains | Flatten to one level |7172---7374## Router Skill Checks (R001-R005)7576Automatically detected for skills mentioning "hub", "router", or "routes to...skills":7778| Check | Description | Severity |79|-------|-------------|----------|80| R001 | Quick Reference table with Risk column | Warning |81| R002 | Risk Legend present | Warning |82| R003 | Negative Triggers documented | Warning |83| R004 | Disambiguation examples | Warning |84| R005 | Context awareness (pronoun resolution) | Info |8586---8788## Risk Level Checks (K001-K003)8990Applied to skills with `scripts/` directory:9192| Check | Description | Severity |93|-------|-------------|----------|94| K001 | Destructive scripts have ⚠️ indicators | Warning |95| K002 | Bulk operations marked as ⚠️⚠️ | Warning |96| K003 | High-risk ops document --dry-run | Warning |9798### Risk Level Reference99100| Risk | Symbol | Operations | Required Safeguards |101|------|:------:|------------|---------------------|102| Safe | `-` | search, list, get, export | None |103| Destructive | `⚠️` | create, update, delete | Confirm |104| High-risk | `⚠️⚠️` | bulk ops, admin changes | Confirm + dry-run |105106---107108## Audit Report Format109110```json111{112 "skill": "my-skill",113 "tokenFootprint": { "level1": 180, "level2": 3200, "level3": 15000 },114 "violations": [...],115 "score": 72,116 "grade": "C"117}118```119120---121122## Related Documentation123124- [Disclosure Level Criteria](docs/disclosure-levels.md)125- [Token Counting Guide](docs/token-counting.md)126- [Naming Conventions](docs/naming-conventions.md)127- [Validation Rules](docs/validation-rules.md)
grandcamel