Optimize CLAUDE.md

Reduces the recurring token cost of CLAUDE.md (and its nested + linked siblings) by identifying paragraph-length entries, redundant content, and hot-path bloat — then trimming or extracting them while preserving the canonical source.

This SKILL.md is a thin index. Detailed rules live in rules/*.md and load on demand. Worked examples live in references/*.md. Reading them all up-front would burn tokens you do not need yet.

When to run

Run when any of these hold:

• Claude Code prints Large CLAUDE.md will impact performance (Xk chars > 40.0k) at session start.
• The user asks "shrink", "optimize", "reduce", or "trim" CLAUDE.md.
• A paragraph in CLAUDE.md exceeds 6 lines and is not a code block.
• An inventory section duplicates content already loaded by the harness (e.g. skill description frontmatter, which is preloaded automatically).
• A nested package CLAUDE.md repeats content from the root.

Refuse if the target file is < 10k chars — see rules/hard-rules.md.

Mode Detection

Parse $ARGUMENTS and detect the mode. First positional is mode; second is optional path (default ./CLAUDE.md).

State the detected mode and target file in one line before continuing:

Mode: audit
Target: /abs/path/to/CLAUDE.md (43,012 chars / ~10,750 tokens)

Workflow

Required Reading by Phase

Load on demand — do not preload.

Core Principles

1. The context window is a public good. Every line in CLAUDE.md is a recurring token cost once loaded, and survives compaction at a per-session slice. Optimize for the smallest hot-path footprint that still preserves the rules an agent must follow.
2. Do not duplicate what the harness already loads. A skill's description frontmatter is preloaded by Claude Code automatically. An inventory paragraph in CLAUDE.md that restates it pays the token cost twice. Replace with a one-line hook + link.
3. Two levers, not one. (a) Shrink the file via trim / extract. (b) Convert rarely-used agent-invokable skills to slash-only via Phase 2.5 — removes their description from the always-on available-skills list. Both reduce per-session context cost.
4. Hot-path stays terse; cold-path moves. Project commands, file pointers, hard invariants → keep in CLAUDE.md. Design rationale, feature history, verbose descriptions → move to linked files.
5. Never delete silently. trim and extract always preserve content somewhere reachable. If you cannot find a destination, abort and ask.
6. The canonical source wins. A skill's own SKILL.md frontmatter is the authority for that skill. Never edit it from this skill — route invocation-flag changes to /create-skill review.

Anti-patterns (one-liners — full list in rules/classification.md)

• Inventory entry that restates a skill's description frontmatter verbatim.
• Paragraph longer than 6 lines describing a single skill or agent.
• Design rationale ("we chose X because Y") in root CLAUDE.md — belongs in the skill's own CLAUDE.md or a rule file.
• Nested package CLAUDE.md that repeats root content.
• Examples of correct/incorrect patterns in CLAUDE.md itself — examples belong in skill files.
• Time-sensitive narrative ("as of 2026-05", "we just added"). Decays into noise.

Composition

• Calls docs skill's Placement Resolver via Skill("docs", "pattern <glob>") when an extraction needs cross-cutting placement (e.g. a rule applies to multiple subtrees).
• References create-skill's token-economics.md and progressive-disclosure.md for the underlying conciseness principles — do not duplicate that guidance here.

Definition of Done

A run is complete when:

• Mode and target file stated in one line.
• Phase 1 metrics captured (total chars, approx tokens, top-10 longest entries).
• Phase 2 classification covers every H2 section.
• Phase 2.5 invocation review run if skills/ exists in the repo; candidates listed with baseline-savings estimates.
• For audit: ranked report emitted with top-N concrete suggestions (lever 1 + lever 2), each tagged hot-path / cold-path or slash-conversion.
• For trim and extract: every applied change shows before/after chars + estimated tokens saved.
• No content silently deleted. No canonical SKILL.md frontmatter edited (route to /create-skill for invocation flag changes).
• If the file is now < 40k chars, report "below performance warning threshold".
• If invocation candidates were suggested, report total estimated baseline savings separately from CLAUDE.md savings.