CLAUDE.md Compactor Skill

---
name: claude-md-compactor
description: Lean a bloated CLAUDE.md back to a tight lookup-table of STABLE operating instructions WITHOUT losing anything — relocate (never delete) dated status, file-catalogs, duplicated content, and procedural walkthroughs to their real homes. Use when a project's CLAUDE.md is over ~200 lines / heavy with status logs, or the user says "lean the CLAUDE.md", "compact claude.md", "optimize claude.md", "claude.md is bloated". The REMOVE/relocate counterpart to `claude-md-improver` (which ADDS) and `memory-compactor` (which compacts MEMORY.md). For the tiered /Agents root, compose with the `context-manager` agent.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
---

# CLAUDE.md Compactor

CLAUDE.md loads into **every session** for its project, so it must be a lean **lookup-table of stable operating instructions** (Anthropic guidance: ≤~200 lines). Bloat = wasted tokens on every message. This skill leans a bloated CLAUDE.md by RELOCATING everything that isn't a stable operating instruction to a real home — **nothing is deleted**, and every load-bearing rule is preserved verbatim.

## The job in one line
Move **status / catalogs / duplicates / procedures** OUT; keep **operating instructions** IN.

## The 5 bloat patterns → their fix (this IS the protocol)
- **P1 — File-catalogs** (folder trees, file-by-file lists): auto-inferable → replace with a 1-line `see <folder>/ (or its README)`.
- **P2 — Dated status / changelog** (revenue, "CURRENT STATUS", production status, "last updated", session logs): goes stale, belongs elsewhere → move to the project's `STATUS.md` (current snapshot) or `PENDING-TASKS.md`.
- **P3 — Duplicated content** (personas, design specs, colors, audience analysis copied from a source file): → link to the source, delete the copy.
- **P4 — Procedural walkthroughs** (multi-step shell pipelines, command sequences): → move to `scripts/` (or a `references/` doc), reference in 1 line.
- **P5 — Over-detailed hierarchy maps** (every version folder + sub-file): → condense to "current version + 1-line pointer".

## KEEP verbatim (load-bearing — never move/cut)
Voice/style rules, CRITICAL/burned-in rules, workflows & pipelines, commands/slash-skills, MCP & tool-selection decision rules, "how to work in this repo" guidance, content standards, key decisions that govern behavior. **When unsure whether a line is an operating instruction, KEEP it.** The risk of cutting a live rule >> the token savings.

## Protocol (do every step; never skip the backup)
1. **Measure.** `wc -l` and `wc -c`. If already lean (≤~200 lines AND no obvious status/catalog/duplicate/procedure bloat), STOP — don't churn. (Watch very-long-line files: low line count can still be huge bytes, e.g. a single 3,700-char status paragraph.)
2. **Read the WHOLE file.** Classify each section: KEEP (operating instruction) vs MOVE (P1–P5).
3. **Back up FIRST (the safety net).** `cp CLAUDE.md CLAUDE.md.bak-<YYYY-MM-DD>` (or ensure it's committed in git). Never edit before backing up.
4. **Relocate each MOVE block to a real home** — `STATUS.md` / `PENDING-TASKS.md` (status), `scripts/` or `references/` (procedures), or a link to the existing source (duplicates), or a 1-line folder pointer (catalogs/trees). Create the home file if needed. **Relocate, never delete.**
5. **Rewrite CLAUDE.md**: all KEEP content verbatim + each moved block replaced by its 1-line pointer.
6. **Migration note**: end with a short HTML comment (free tokens) listing what moved where, e.g. `<!-- compacted YYYY-MM-DD: CURRENT STATUS → STATUS.md; folder tree → see dir; image pipeline → scripts/. Backup: CLAUDE.md.bak-YYYY-MM-DD -->`.
7. **Verify.** `wc -l` ≤ target; `diff CLAUDE.md.bak-<date> CLAUDE.md` shows ONLY status/catalog/duplicate/procedure moved (no operating rule lost); confirm each moved block now exists at its new home.

## Hard rules
- Back up before editing. Relocate, never delete. Keep every operating instruction verbatim.
- CLAUDE.md is a lookup-table, not a brain-dump. If a fact is inferable from the codebase or lives in a source file, link to it.
- HTML comments (`<!-- -->`) are stripped before injection = free tokens; use them for rationale/migration notes Claude doesn't need at runtime.
- One project at a time; for active/high-traffic projects, hand the leaned file to the user for review before locking.

## Composes with
- `memory-compactor` — the MEMORY.md (auto-memory index) counterpart.
- `context-manager` agent — tier health for the /Agents root (run it there in addition to this).
- `claude-md-improver` — ADDS missing commands/gotchas; run AFTER leaning if the file has real gaps.