Optimize Claude Md

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 ")` when an extraction needs cross-cutting placement (e.g. a rule applies to multiple subtrees).

• References [create-skill](../create-skill/SKILL.md)'s

[token-economics.md](../create-skill/rules/token-economics.md) and [progressive-disclosure.md](../create-skill/rules/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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mthines
• Source: mthines/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.