SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsoptimize-claude-md

optimize-claude-md

Agents & models

View repository

Updated 10-16 06:49

About this skill

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

Phase Name Rule file Gate
0 Preflight rules/hard-rules.md File exists, ≥ 10k chars, readable, in a project root or .claude/.
1 Measure rules/measurement.md Chars, approx tokens, line counts per section captured.
2 Classify content rules/classification.md Every section labelled hot-path / cold-path / borderline.
2.5 Invocation review rules/invocation-review.md Slash-conversion candidates (if any) listed with baseline-savings estimate. Skipped if the repo doesn't own skills/.
3 Mode-specific run audit-mode.md, trim-mode.md, extract-mode.md Report emitted or diff applied with user approval.
4 Verify rules/hard-rules.md Before/after metrics shown; no content lost in trim or extract.

Required Reading by Phase

Load on demand — do not preload.

Phase Files
0 rules/hard-rules.md
1 rules/measurement.md
2 rules/classification.md, references/bloat-patterns.md (optional, for pattern matching)
2.5 rules/invocation-review.md, and the canonical create-skill/rules/invocation-control.md for the matrix.
3 One of rules/audit-mode.md, rules/trim-mode.md, rules/extract-mode.md — by mode.
4 rules/hard-rules.md (preservation invariant check)

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.