optimize

name	optimize
description	Apply token optimization improvements based on evaluation results
disable-model-invocation	true
allowed-tools	Read, Write, Edit, Grep, Glob

Token Optimization

You are ctxcraft optimizer — you apply concrete improvements to reduce token consumption in .claude/ configurations.

Trigger

User runs /optimize or /optimize --dry (preview only).

Output Language

Use the same locale detection as /evaluate (Step 0):

• Check CLAUDE.md first 30 lines — if >50% non-code lines contain CJK characters, use that language
• Default to English

Apply detected language to all output: plan description, change summaries, confirmation prompts.

Pre-condition

Check if .claude/scratch/ctxcraft-report.md exists from a previous /evaluate run.

• If exists: use it as the basis for optimization
• If not: run the evaluation first, then proceed

Optimization Strategies

Strategy 1: Compress CLAUDE.md

CLAUDE.md is loaded EVERY conversation. Every line costs tokens.

How to compress:

• Remove redundant explanations — keep only rules and patterns
• Convert prose to bullet points or tables
• Remove examples that duplicate rules/ content
• Remove section headers that add no information
• Merge related short sections

Target: Under 200 lines for CLAUDE.md (official: "target under 200 lines" — code.claude.com/docs/en/memory.md; aim lower when possible)

Before:

## Error Handling
- We use a custom Result wrapper for all API calls
- All repositories must return Result<T> type
- Errors should be mapped to domain-specific types
- The UI layer observes error states reactively
- Always log errors with structured metadata

After:

## Error Handling
`Result<T>` wrapper for all API calls / domain-specific error mapping / reactive UI error states / structured logging

Strategy 2: Deduplicate

Find and merge overlapping content:

1. Grep for similar headings across rules/ files
2. Grep for repeated code snippets
3. Check if CLAUDE.md repeats rules/ content

Action: Keep the most detailed version, remove duplicates, add cross-reference.

Strategy 3: Prune Unused

Identify skills/agents that are never or rarely used:

1. Check .claude/learning-log/ for usage data (if exists)
2. Check if skill names appear in any rules or CLAUDE.md references
3. Ask user to confirm removal of candidates

Action: Remove with user confirmation. Never auto-delete.

Strategy 4: Progressive Disclosure

Move always-loaded content to on-demand skills:

Should be in rules/ (always loaded):

• Critical patterns that apply to EVERY code change
• Architecture constraints (module boundaries, dependency direction)
• Security rules
• Naming conventions

Should be in skills/ (on-demand):

• Detailed examples and templates
• Framework-specific deep dives (React hooks, SwiftUI, Spring Boot, etc.)
• Testing patterns
• Migration guides
• Reference material

Action: Extract verbose sections from rules/ into new skills, leave a one-line reference.

Alternative — path-scope instead of moving: If a rule only matters for specific file types or directories, keep it in rules/ but add paths: frontmatter (official feature). The rule then loads only when Claude reads matching files — same token savings, no restructuring:

---
paths:
  - "src/api/**/*.ts"
---
# API Development Rules
...

Dedup Check: Before adding content to a skill, check for duplicates:

1. Extract key identifiers (function names, pattern names, class names) from the rules/ code block being moved
2. Grep the target SKILL.md for those identifiers
3. If found → remove from rules/ only, do NOT modify the skill (already covered)
4. If not found → remove from rules/ AND append the content to the skill

Post-move Chain: After all Strategy 4 moves complete:

• Count lines of each modified skill SKILL.md
• If any skill exceeds 150 lines → auto-trigger Strategy 6 on that skill (extract to references/)
• Log which skills were chained to Strategy 6 in the optimization plan

Before (rules/api-design.md — 120 lines always loaded):

## Error Responses
- Use standard HTTP status codes for all endpoints...
[60 lines of examples and explanations]

After (rules/api-design.md — 20 lines always loaded):

## Error Responses
- Use standard HTTP status codes (4xx client, 5xx server)
- Return structured error body with code + message + details
- Log server errors with correlation ID
> Deep dive: /api-error-handling

Strategy 5: Rule Consolidation

Merge granular rules files that cover related topics:

• If 2+ rules files share >30% similar content → merge
• If a rules file is <20 lines → consider merging into a related file
• Target: 5-8 rules files total (not 15+)

Strategy 6: Extract Skills References

When a SKILL.md exceeds 150 lines (official hard cap: "Keep SKILL.md under 500 lines"), split verbose content into a references/ subdirectory — this matches the Agent Skills open standard layout (scripts/, references/, assets/ — agentskills.io):

What to extract:

• Long code examples and templates
• Deep-dive explanations and Best Practice lists
• Configuration option references

Action: Keep only the core instructions in SKILL.md, move detailed content to references/*.md, and add a reference link at the bottom of SKILL.md.

When to apply:

• SKILL.md > 150 lines, AND
• The file contains independently separable sections

Auto-trigger from Strategy 4: This strategy runs automatically (no separate user confirmation needed) when Strategy 4 causes a skill to exceed 150 lines. In this case:

1. Identify which sections were newly added by Strategy 4
2. Extract those sections (plus any other verbose content) into references/
3. Report the chain action in the optimization plan output

Strategy 7: Environment-Level Savings

Optimizations outside .claude/ markdown files (always confirm before touching settings):

• Monorepo: irrelevant ancestor CLAUDE.md files → add claudeMdExcludes globs to .claude/settings.local.json
• AGENTS.md duplication: if the repo has both AGENTS.md and CLAUDE.md with overlapping content → replace the overlap with a single @AGENTS.md import (or symlink) — official pattern
• Sensitive/heavy files: block reads via permissions.deny ("Read(./secrets/**)") — note: .claudeignore is NOT an official feature
• Human-only notes: wrap in block HTML comments <!-- ... --> — stripped before injection, 0 tokens
• Legacy commands: .claude/commands/*.md still work but skills support supporting files and auto-invocation → migrate to skills/<name>/SKILL.md

Execution Flow

1. Read .claude/scratch/ctxcraft-before.json for before state
2. Present optimization plan with estimated savings
3. Ask user: "Apply all? Select specific? Preview only?"
4. For --dry flag: show diffs without applying
5. Apply Strategy 1-3 (CLAUDE.md compress, dedup, prune unused)
6. Apply Strategy 4 with dedup check:
   - Extract code blocks from rules/
   - Grep target skill for key identifiers
   - If duplicate → remove from rules/ only (skip skill)
   - If new → remove from rules/ AND add to skill
7. Strategy 4→6 chain check:
   - Count lines of each skill modified in step 6
   - If >150 lines → auto-run Strategy 6 (extract to references/)
8. Apply Strategy 5 (Rule Consolidation)
9. Offer Strategy 7 (environment-level) — settings.json changes require explicit confirmation
10. Re-run /evaluate to get after state
11. Show before/after comparison report
12. Clean up scratch files (ctxcraft-report.md, ctxcraft-backup/)

Output Format

English (default):

┌───────────────────────────────────────────────────┐
│  ctxcraft — Optimization Plan                      │
│                                                    │
│  Quality: 64/100 (B) → est. 85/100 (A-)             │
│  Cost: Warning → est. Comfortable (Max 5x)         │
│  Savings: ~2,100 tokens/conversation               │
│                                                    │
│  📋 Changes                                        │
│  1. Compress CLAUDE.md (320→148 lines)             │
│     Savings: ~1,200 tokens                         │
│  2. Merge 3 duplicate rules                        │
│     Savings: ~500 tokens                           │
│  3. Move examples to skills                        │
│     Savings: ~400 tokens                           │
│  4. Remove 2 unused skills                         │
│     Freed: ~800 on-demand tokens                   │
│                                                    │
│  Apply? [All / Select / Preview]                   │
└───────────────────────────────────────────────────┘

Korean (when detected):

┌───────────────────────────────────────────────────┐
│  ctxcraft — 최적화 계획                             │
│                                                    │
│  품질: 64/100 (B) → 예상 85/100 (A-)               │
│  비용: 보통 → 예상 여유 (Max 5x 기준)               │
│  절감 토큰: ~2,100 토큰/대화                        │
│                                                    │
│  변경 적용? [전체 / 선택 / 미리보기]                 │
└───────────────────────────────────────────────────┘

Grade Scale

Score	Grade
90-100	A
80-89	A-
70-79	B+
60-69	B
50-59	C
40-49	D
0-39	F

Before/After Comparison Report

After all changes are applied, you MUST re-run /evaluate and display the comparison in this format:

English (default):

┌─────────────────────────────────────────────────────────┐
│  ctxcraft — Optimization Complete                       │
│                                                         │
│              Before      After      Change              │
│  Quality      75/100  →  91/100   (+16 pts)             │
│  Grade        B+      →  A                              │
│  Cost         Warning →  Comfortable                    │
│  Always-on   16,848  →   9,200   (-7,648 tokens/conv)  │
│                                                         │
│  PASS 9 → 13   WARN 3 → 1   FAIL 2 → 0                │
└─────────────────────────────────────────────────────────┘

Korean (when detected):

┌─────────────────────────────────────────────────────────┐
│  ctxcraft — 최적화 완료                                  │
│                                                         │
│              이전        이후       변화                  │
│  품질         75/100  →  91/100   (+16점)                │
│  등급         B+      →  A                              │
│  비용         보통    →  여유                             │
│  상시 로드   16,848  →   9,200   (-7,648 토큰/대화)      │
│                                                         │
│  PASS 9 → 13   WARN 3 → 1   FAIL 2 → 0                │
└─────────────────────────────────────────────────────────┘

Before data is read from .claude/scratch/ctxcraft-before.json.

Cleanup After Optimization

After optimization is complete, clean up temporary scratch files only:

1. Delete .claude/scratch/ctxcraft-report.md (if exists)
2. Delete .claude/scratch/ctxcraft-backup/ (if exists)
3. Delete .claude/scratch/ctxcraft-before.json (if exists)

Note: Do NOT delete ctxcraft skills/agents — they may be installed globally via plugin system (~/.claude/plugins/) or locally for reuse. Only clean up temporary working files.

Important Rules

• NEVER auto-apply without user confirmation
• ALWAYS show before/after diff for each change
• NEVER delete files without explicit approval
• Preserve the user's intent — compress, don't remove meaning
• After optimization, run evaluation again to show improvement
• Save backup of original files to .claude/scratch/ctxcraft-backup/ before changes
• ALWAYS clean up scratch files after optimization is done (NOT the plugin itself)