Claude md
Shrink an oversized CLAUDE.md. Measures what the project's always-loaded instructions cost per turn, then works through it section by section — cutting what the codebase already says, moving path-specific guidance to .claude/rules/ and prompt-specific conventions to .clawness/rules/, and leaving load-bearing "don't undo this" content where it is. Destructive and deliberate: run it when you have the session to spend.From its SKILL.md
npx -y skills add fullymiddleaged/Clawness --skill claude-mdAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
8.2 KB, as published. Nobody here has run it
Shrink CLAUDE.md
CLAUDE.md is loaded by the harness, in full, at the start of every session and
re-read after /compact. It is the one context cost nothing can cap: Clawness's
rules block is budgeted, the lessons log is ranked and budgeted, CLAUDE.md is
neither. Files past ~200 lines also measurably reduce how reliably Claude follows
any single instruction in them, so a big CLAUDE.md costs twice — tokens, and the
adherence of the rules you actually cared about.
This skill is the remedy. The Clawness SessionStart check is only the diagnosis: it reports the number once and deliberately refuses to start this work, because it fires before you've said what you came for. You invoking this skill is the consent that note couldn't ask for.
Say this before starting. This is a destructive reorganisation of a file the user may care about a great deal, and it takes a while. Tell them: it will take most of a session, nothing is deleted until its replacement is verified, and they can stop after any single section. Then get an explicit go-ahead.
First: is this the right tool?
Claude Code ships /doctor (alias /checkup, v2.1.206+), which proposes CLAUDE.md
trims natively and migrates what remains into skills and nested CLAUDE.md files. It
reports before changing anything.
- If the project does not use Clawness project rules, say so and recommend
/doctorinstead. It is maintained by the harness and knows more about how instructions load than this skill does. Do not compete with it out of loyalty. - This skill earns its place when the project uses Clawness, because it has two
destinations
/doctordoesn't know exist:.clawness/rules/(retrieved by relevance and budgeted, with no line cap and the full rule format) and.clawness/memory.md(one-line traps). Running both is fine and they compose —/doctorfor the trim, this for the Clawness-specific placement.
What actually reduces per-turn cost
Only two harness mechanisms do, plus Clawness's own retrieval. Get this right or the whole exercise is theatre:
| Destination | When it loads | Use for |
|---|---|---|
CLAUDE.md | every session, in full | short, always-true, load-bearing |
.claude/rules/*.md with paths: frontmatter | when Claude reads a matching file | guidance tied to specific files or directories |
nested <subdir>/CLAUDE.md | when Claude reads files in that subdir | guidance tied to one area of the tree |
.clawness/rules/*.yml | ranked per prompt, inside CLAW_BUDGET | conventions tied to a topic rather than a path |
.clawness/memory.md | ranked per prompt, ~3 lines | one-line traps that bit once |
| skills | when invoked or judged relevant | multi-step procedures |
@path imports do NOT reduce cost, and neither do .claude/rules/ files without
paths: frontmatter. Imports are expanded and loaded at launch, recursively to
four hops; un-scoped rules load every session at the same priority as CLAUDE.md.
Reorganising a 9,000-token CLAUDE.md into @ references is the most common version
of this task, and it moves exactly zero tokens. If the user proposes it, tell them
plainly before they spend the session on it.
Steps
1. Measure
Read CLAUDE.md, plus CLAUDE.local.md and .claude/CLAUDE.md if present — the
harness loads all of them, so the cost is the sum. Report:
- total characters and a rough token estimate (chars ÷ 4; call it rough, it is)
- a per-section breakdown by top-level heading, largest first
The breakdown is the point. "Your CLAUDE.md is 9k tokens" invites a shrug; "your
Architecture section alone is 3.4k tokens and describes files Claude can read" does
not. Do not follow @path imports for the measurement unless the user asks — say
that the real number is higher if any exist.
2. Classify every section
Go heading by heading and assign one of five verdicts. Default to STAY. The burden of proof is on moving something, not on keeping it.
- STAY — anything shaped like "don't undo this without reading why", "we tried X and it broke", or a constraint that is invisible from the code. This is load-bearing precisely when the prompt gives no hint that it applies, so retrieval can't be trusted to surface it. A missed ranked rule is a slightly worse answer; a missed "don't undo this" is the regression it existed to prevent. Also STAY: build/test commands, and short conventions that differ from tool defaults.
- CUT — anything the codebase already answers: directory layouts, dependency
lists, architecture summaries, file inventories, restatements of
package.jsonscripts or theMakefile, and history that reads as a changelog. - →
.claude/rules/<topic>.md— applies only when touching certain files. Needspaths:frontmatter with globs, or it loads every session and you have achieved nothing. Check the globs against a real file in the repo before moving on. - →
.clawness/rules/<domain>/<ID>.yml— a durable convention tied to a topic rather than a path (naming, error handling, a library's house style). Full rule format:id, domain, severity, tags, triggers, when, rule, violation, correct.tagsandtriggersdrive retrieval — put the words someone would actually type. - →
.clawness/memory.md— one-line traps only, under## Lessons, 120 chars max, naming the file or flag so it retrieves. If the rationale is the payload, it is not a memory entry; the line cap will shred it. Use.clawness/rules/instead.
Present the whole classification as a table and get approval before moving anything. Include the projected token saving so the user can judge whether it is worth their session.
3. Move one section at a time, verify, then delete
Never delete the original until its replacement is proven to surface. For each approved section, in order, smallest first:
- Write the new file (or add the rule).
- Verify it:
.clawness/rules/→ confirm the new ID retrieves. TheclawnessCLI ships with the plugin but isn't on PATH; run it via the wrapper the SessionStart bootstrap writes each session:CLAW="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/clawness/clawness-cli.sh", thenbash "$CLAW" query "<a prompt this should match>"and check the ID appears. (Editable/manual installs may usepython -m clawness.cli query ....).claude/rules/withpaths:→ confirm the glob matches a real file in the repo. It loads when Claude reads a matching file, so it cannot be proven from inside this turn; say that rather than implying you tested it..clawness/memory.md→ the entry is one line under## Lessons.
- Only then remove the section from CLAUDE.md.
- Say what moved and what the file is down to.
If verification fails, put the section back and mark it STAY. A rule that doesn't retrieve is strictly worse than a paragraph in CLAUDE.md.
4. Finish
- Re-measure and report the before/after.
- If anything moved to
.clawness/rules/, runbash "$CLAW" lint— it rejects missing fields and vague phrasing, and a rule that fails lint won't survive CI in projects that gate on it. - Remind the user that new
.claude/rules/and.clawness/rules/files load on the next session, not this one. - Suggest committing the result as one reviewable change, so the move can be read and reverted as a unit.
Don't
- Don't start this from a SessionStart note, a passing mention, or your own initiative. It is opt-in work.
- Don't move something because it is long. Move it because it is conditional.
- Don't rewrite prose while relocating it. Move it verbatim, then trim in a separate pass if the user wants — a reorganisation that also silently reworded the rules is impossible to review.
- Don't touch
~/.claude/CLAUDE.mdor a managed-policy CLAUDE.md. This is about the project's file.