Claude Md Slim

CLAUDE.md Slim — Page Out the Bloat

Makes the root CLAUDE.md minimal by keeping only what every session needs always-on and moving everything else to docs/ behind one-line pointers. The inverse objective of claude-md-improver: that skill's gradient points at completeness (it adds), this one's points at minimal always-on context (it extracts). Opposite gradients, so opposite skills — don't ask the improver to slim, it structurally can't.

Why this exists (the evidence). "Less Context, Better Agents" (Lodha et al., arXiv:2606.10209) found that full always-on history hit 71% task completion at 1.48M tokens, while pruned + summarized context hit 91.6% at ~553K — less always-on context, detail retrieved on demand, is both cheaper and more reliable. CLAUDE.md is loaded into every session whether or not the task touches it; it is the always-on-history problem in miniature.

The load-time fact that makes or breaks this. Paging out only helps if the pointer is loaded lazily:

This skill uses plain-path pointers, NEVER @-imports. An @-import feels like splitting while paying the full token bill — it defeats the entire purpose.

Where it sits in the family:

• claude-md-improver — audit for completeness/quality; adds.
• claude-md-slim — cut always-on size; extracts. This skill.

Fixer, not finder (unlike /architect-review-pr, /blind-spot). It edits CLAUDE.md and writes docs/ files — so it confirms the triage plan before applying, and moves rather than deletes (no information is lost; the root just gets smaller and the detail becomes reachable-on-demand).

The triage rule (the whole point)

For each block/bullet in the target CLAUDE.md, ask: does this apply to EVERY task, or only when touching a specific area?

STAYS always-on — session-invariant rules, true regardless of what you're doing:

• Safety / non-negotiable constraints (things that must never happen).
• Build / test / lint / run commands (needed constantly).
• Repo-wide gates on any edit: commit-message format, branch rules, "run X before commit".
• One-line "what this is" orientation.
• The pointer index to docs/ (added by this skill).

PAGES OUT to docs/<topic>.md — detail that only matters when in that area:

• Per-skill / per-feature / per-subsystem deep conventions.
• Long rationale ("why we did X this way") essays.
• Enumerations of edge-case rules for one component.
• Anything a session that never touches that area would never need.

Tie-breaker: if you're unsure whether a block is invariant, page it out — a missed pointer costs one on-demand read; a kept paragraph costs every session forever.

Flow

1. Locate the target. Default: the repo-root CLAUDE.md. If an argument names a path, use it. Confirm the file exists; if there's no CLAUDE.md, say so and stop — there's nothing to slim.

2. Baseline. Record current size: wc -lc <path>. This is the before-number the final check compares against.

3. Triage. Read the whole file. Classify every block per the rule above into STAYS vs a named docs/<topic>.md bucket. Group paged-out blocks by natural topic (one doc per subsystem/skill/concern — don't scatter into 30 tiny files).

4. Present the plan — do not edit yet. Show a table: each paged-out topic → target docs/ path → the one-line pointer that will replace it in root; and the list of blocks that STAY. State the projected root size. Ask the user to approve, adjust the split, or cancel. This confirm gate is mandatory — CLAUDE.md is the user's project memory.

5. Apply (on approval).

   • Write each docs/<topic>.md with the extracted blocks verbatim (move, don't rewrite — preserve the exact wording so nothing is lost).
   • Rewrite root CLAUDE.md: the STAYS blocks, plus a short plain-path pointer index — e.g. - Auth internals & conventions: see docs/auth.md. Plain paths only; never @docs/....
   • Leave everything uncommitted — the maintainer owns git.

6. Verify the win (mandatory pre-return check). Re-run wc -lc <path> and report before → after for the root, and confirm every paged-out block now lives in a docs/ file (grep a distinctive phrase from each extracted section in its new home). If the root didn't actually shrink, or any block is missing from both root and docs, the slim failed — say so, don't claim success.

Key rules

• Move, never delete. Every paged-out block lands verbatim in a docs/ file. The no-data-loss guarantee is non-negotiable — this is a reorganizer, not a trimmer.
• Plain-path pointers only, never @-imports — an @-import stays eagerly loaded and defeats the skill.
• Confirm before applying — the plan (step 4) is shown and approved before any file is written; CLAUDE.md is precious.
• Everything uncommitted — reports and edits are left for the maintainer to review and commit.
• Root stays coherent — a slimmed CLAUDE.md must still read as a complete orientation on its own (what this is + the invariant rules + where to find the rest), not a stub of dangling links.
• Scope to the target file. Handle nested CLAUDE.md files only if the user names them — don't sweep the tree.