mthinesmthines/agent-skills/skills/authoring/optimize-claude-md/SKILL.md

optimize-claude-md

Skill20 starsChanged 13 days agoMITView on GitHub

Audits CLAUDE.md files and `.claude/rules/` for context bloat and emits ranked fixes — trim inventory entries, extract sections, flag rarely-used skills for slash-only. Invoke with /optimize-claude-md [audit|trim|extract] for "CLAUDE.md is too big" or the large-CLAUDE.md warning.

In this repository48 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- skills/workflow/autonomous-workflow/CLAUDE.mdCLAUDE.md
- ideateSkill
- interviewSkill
- playwright-trace-analyzerSkill
- profile-optimizerSkill
- rum-trackingSkill
- screencastSkill
- video-analyserSkill
- youtube-transcriptSkill
- create-skillSkill
- docsSkill
- handoffSkill
- persistent-memorySkill
- attach-mediaSkill
- ci-auto-fixSkill
- create-prSkill
- github-actions-authorSkill
- resolve-conflictsSkill
- animations-nativeSkill
- animationsSkill
- behavioral-designSkill
- chartingSkill
- storybookSkill
- uxSkill
- visual-designSkill
- ai-engineeringSkill
- confidenceSkill
- criticalSkill
- impact-mapSkill
- jev-assertSkill
- measurableSkill
- optimize-approachSkill
- polishSkill
- pr-reviewSkill
- review-loopSkill
- tddSkill
- verify-behaviorSkill
- aw-verifySkill
- e2e-testing-mobileSkill
- e2e-testingSkill
- telemetry-verifySkill
- ui-verifySkill
- autonomous-workflowSkill
- aw-create-planSkill
- aw-create-walkthroughSkill
- fix-bugSkill
- implement-suggestionSkill

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Run when any of these hold:
line 42
Distinctive:
The context window is a public good: Every line in CLAUDE.md is a recurring token cost once loaded, and survives compaction at a …
line 105

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.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 < 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

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 — hand invocation-flag changes to the user as a frontmatter edit to apply.

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).

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 (hand invocation-flag changes to the user as an edit).
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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free