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).
| Mode |
Default |
Trigger |
audit |
yes |
Default. Or audit, "review", "report", no mode argument. |
trim |
|
trim, "shorten", "condense", "make entries one-liners". |
extract |
|
extract, "move to file", "split out", "externalize inventory". |
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
- 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.
- 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.
- 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.
- 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.
- Never delete silently.
trim and extract always preserve content
somewhere reachable. If you cannot find a destination, abort and ask.
- 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.
- 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
Definition of Done
A run is complete when:
1---2name: optimize-claude-md3description: Audits CLAUDE.md files (root, nested, `.claude/rules/*.md`) for context bloat and emits ranked suggestions across two levers — (1) shrink inventory entries, (2) flag rarely-used agent-invokable skills that should become slash-only to drop their description from the always-on available-skills list. Triggers on Claude Code's "Large CLAUDE.md will impact performance" warning (> 40k chars), inventory entries duplicating harness-loaded skill descriptions, "CLAUDE.md is too big", "shrink CLAUDE.md", "optimize CLAUDE.md", "/optimize-claude-md". Three modes — `audit` (read-only ranked report + slash-conversion candidates), `trim` (interactive one-line hook + diff approval), `extract` (moves sections to linked files preserving content). Composes with `docs` (Placement Resolver) and `create-skill` (invocation matrix). Hard rules: refuses files < 10k chars; never deletes silently; never edits any skill's canonical `SKILL.md` frontmatter — routes to `/create-skill`.4license: MIT5---67# Optimize CLAUDE.md89Reduces the recurring token cost of `CLAUDE.md` (and its nested + linked10siblings) by identifying paragraph-length entries, redundant content, and11hot-path bloat — then trimming or extracting them while preserving the12canonical source.1314> **This `SKILL.md` is a thin index.** Detailed rules live in `rules/*.md`15> and load on demand. Worked examples live in `references/*.md`. Reading16> them all up-front would burn tokens you do not need yet.1718---1920## When to run2122Run when **any** of these hold:2324- Claude Code prints `Large CLAUDE.md will impact performance (Xk chars > 40.0k)` at session start.25- The user asks "shrink", "optimize", "reduce", or "trim" CLAUDE.md.26- A paragraph in CLAUDE.md exceeds 6 lines and is not a code block.27- An inventory section duplicates content already loaded by the harness28 (e.g. skill `description` frontmatter, which is preloaded automatically).29- A nested package `CLAUDE.md` repeats content from the root.3031Refuse if the target file is < 10k chars — see [`rules/hard-rules.md`](./rules/hard-rules.md).3233---3435## Mode Detection3637Parse `$ARGUMENTS` and detect the mode. First positional is mode; second is38optional path (default `./CLAUDE.md`).3940| Mode | Default | Trigger |41| --------- | ------- | ---------------------------------------------------------------- |42| `audit` | **yes** | Default. Or `audit`, "review", "report", no mode argument. |43| `trim` | | `trim`, "shorten", "condense", "make entries one-liners". |44| `extract` | | `extract`, "move to file", "split out", "externalize inventory". |4546State the detected mode and target file in one line before continuing:4748```49Mode: audit50Target: /abs/path/to/CLAUDE.md (43,012 chars / ~10,750 tokens)51```5253---5455## Workflow5657| Phase | Name | Rule file | Gate |58| ----- | ------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------- |59| 0 | Preflight | [`rules/hard-rules.md`](./rules/hard-rules.md) | File exists, ≥ 10k chars, readable, in a project root or `.claude/`. |60| 1 | Measure | [`rules/measurement.md`](./rules/measurement.md) | Chars, approx tokens, line counts per section captured. |61| 2 | Classify content | [`rules/classification.md`](./rules/classification.md) | Every section labelled hot-path / cold-path / borderline. |62| 2.5 | Invocation review | [`rules/invocation-review.md`](./rules/invocation-review.md) | Slash-conversion candidates (if any) listed with baseline-savings estimate. Skipped if the repo doesn't own `skills/`. |63| 3 | Mode-specific run | [`audit-mode.md`](./rules/audit-mode.md), [`trim-mode.md`](./rules/trim-mode.md), [`extract-mode.md`](./rules/extract-mode.md) | Report emitted or diff applied with user approval. |64| 4 | Verify | [`rules/hard-rules.md`](./rules/hard-rules.md) | Before/after metrics shown; no content lost in `trim` or `extract`. |6566---6768## Required Reading by Phase6970Load on demand — do not preload.7172| Phase | Files |73| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |74| 0 | [`rules/hard-rules.md`](./rules/hard-rules.md) |75| 1 | [`rules/measurement.md`](./rules/measurement.md) |76| 2 | [`rules/classification.md`](./rules/classification.md), [`references/bloat-patterns.md`](./references/bloat-patterns.md) (optional, for pattern matching) |77| 2.5 | [`rules/invocation-review.md`](./rules/invocation-review.md), and the canonical [`create-skill/rules/invocation-control.md`](../create-skill/rules/invocation-control.md) for the matrix. |78| 3 | One of [`rules/audit-mode.md`](./rules/audit-mode.md), [`rules/trim-mode.md`](./rules/trim-mode.md), [`rules/extract-mode.md`](./rules/extract-mode.md) — by mode. |79| 4 | [`rules/hard-rules.md`](./rules/hard-rules.md) (preservation invariant check) |8081---8283## Core Principles84851. **The context window is a public good.** Every line in `CLAUDE.md` is a86 recurring token cost once loaded, and survives compaction at a per-session87 slice. Optimize for the smallest hot-path footprint that still preserves88 the rules an agent must follow.892. **Do not duplicate what the harness already loads.** A skill's90 `description` frontmatter is preloaded by Claude Code automatically. An91 inventory paragraph in `CLAUDE.md` that restates it pays the token cost92 twice. Replace with a one-line hook + link.933. **Two levers, not one.** (a) Shrink the file via `trim` / `extract`.94 (b) Convert rarely-used agent-invokable skills to slash-only via Phase95 2.5 — removes their description from the always-on available-skills96 list. Both reduce per-session context cost.974. **Hot-path stays terse; cold-path moves.** Project commands, file98 pointers, hard invariants → keep in `CLAUDE.md`. Design rationale,99 feature history, verbose descriptions → move to linked files.1005. **Never delete silently.** `trim` and `extract` always preserve content101 somewhere reachable. If you cannot find a destination, abort and ask.1026. **The canonical source wins.** A skill's own `SKILL.md` frontmatter is103 the authority for that skill. Never edit it from this skill — route104 invocation-flag changes to `/create-skill review`.105106---107108## Anti-patterns (one-liners — full list in [`rules/classification.md`](./rules/classification.md))109110- Inventory entry that restates a skill's `description` frontmatter verbatim.111- Paragraph longer than 6 lines describing a single skill or agent.112- Design rationale ("we chose X because Y") in root `CLAUDE.md` — belongs in the skill's own `CLAUDE.md` or a rule file.113- Nested package `CLAUDE.md` that repeats root content.114- Examples of correct/incorrect patterns in `CLAUDE.md` itself — examples belong in skill files.115- Time-sensitive narrative ("as of 2026-05", "we just added"). Decays into noise.116117---118119## Composition120121- Calls [`docs` skill](../docs/SKILL.md)'s Placement122 Resolver via `Skill("docs", "pattern <glob>")` when an extraction123 needs cross-cutting placement (e.g. a rule applies to multiple subtrees).124- References [`create-skill`](../create-skill/SKILL.md)'s125 [`token-economics.md`](../create-skill/rules/token-economics.md) and126 [`progressive-disclosure.md`](../create-skill/rules/progressive-disclosure.md)127 for the underlying conciseness principles — do not duplicate that128 guidance here.129130---131132## Definition of Done133134A **run** is complete when:135136- [ ] Mode and target file stated in one line.137- [ ] Phase 1 metrics captured (total chars, approx tokens, top-10 longest entries).138- [ ] Phase 2 classification covers every H2 section.139- [ ] Phase 2.5 invocation review run if `skills/` exists in the repo; candidates listed with baseline-savings estimates.140- [ ] For `audit`: ranked report emitted with top-N concrete suggestions (lever 1 + lever 2), each tagged hot-path / cold-path or slash-conversion.141- [ ] For `trim` and `extract`: every applied change shows before/after chars + estimated tokens saved.142- [ ] No content silently deleted. No canonical `SKILL.md` frontmatter edited (route to `/create-skill` for invocation flag changes).143- [ ] If the file is now < 40k chars, report "below performance warning threshold".144- [ ] If invocation candidates were suggested, report total estimated baseline savings separately from CLAUDE.md savings.
mthines