CLAUDE.md Progressive Disclosurer
Restructures a bloated CLAUDE.md / AGENTS.md into a lean Level 1 plus on-demand Level 2 references, with verified zero information loss.
Dev & CodingAdvanced★ 1,323⑂ 212AI score 9/10Last updated: Aug 8, 2026
What it does
Turns "slim down my CLAUDE.md" into a measured, verifiable refactor:
- Profile first:
/contextshare of the startup context, per-heading byte table (work in descending order), giant-line distribution, and downstream truncation limits (e.g. Codexproject_doc_max_bytes, 32KiB default — anything beyond is silently invisible). - Signal triage: the litmus is "if I delete this, will Claude get it wrong?" Anything inferable from the code, standard language conventions, or self-evident advice is an anti-signal — listed as a deletion candidate and removed only with user confirmation.
- Verbatim moves, compression forbidden: moving to Level 2 must copy text unchanged; 3+ sections use
scripts/sink_sections.pywith full-string verification and automatic rollback. - Carrier selection matrix: decides whether a rule belongs in resident Level 1, a reference, a Skill, a Hook (blocking vs injecting), or
~/.claude/rules/withpaths:frontmatter. - Three-part verification: reference existence (5a), content integrity (5b — an independent sub-agent audit is the default, forking banned), and line count explicitly excluded as a criterion (5c).
- Documents how the verifiers themselves lie:
grep -Fdegrades to per-line OR on multi-line originals (false pass for lossy moves), symlinks silently skipped, regex metacharacters, bash vs zsh word splitting — all field-tested.
Who it's for
- Teams whose CLAUDE.md has grown so large that Claude keeps ignoring rules
- Anyone who wants to reorganize guidance without losing a single useful detail
- Users whose global
~/.claude/CLAUDE.mdis polluted with project-specific paths - People sharing the same doc with Codex or other tools that may truncate it silently
Examples
- "Is my CLAUDE.md too long?" → the skill reframes (line count is a symptom, not a goal), then produces a per-section byte table and attacks the biggest contributor first.
- Cleaning a 168KB global file → identifies it as 69% of session startup context, sinks 10 low-frequency SOP sections verbatim into
~/.claude/references/, and adds trigger-keyed index tables at the top and bottom. - Hunting fake pointers → a line says "see
anti-patterns.md" but the content was never moved there; caught via distinctive-stringgrep -Fplus a python3 whole-string containment check.
· · · Install guide · · ·
Install in the Claude app (no terminal)
- Download the ZIP with the button below.
- In Claude, open Settings → Capabilities and turn on 'Code execution and file creation'. (one time)
- Go to Customize → Skills → + → 'Upload a skill' and upload the ZIP.
Install in Claude Code
Let Claude do it — paste this into Claude Code
Install the skill I found on Claude Skill Mart. Copy the daymade-claude-code/claude-md-progressive-disclosurer folder from the GitHub repo daymade/claude-code-skills into my ~/.claude/skills/claude-md-progressive-disclosurer/. When it's done, tell me in one line what this skill can do.
Install with a command instead
git clone https://github.com/daymade/claude-code-skills.git && mkdir -p ~/.claude/skills && cp -r claude-code-skills/daymade-claude-code/claude-md-progressive-disclosurer ~/.claude/skills/⚠ This is a third-party skill. Check the source repository before installing.
- Open a terminal and cd into any working directory.
- Clone the repo:
git clone https://github.com/daymade/claude-code-skills.git - Create the skills directory:
mkdir -p ~/.claude/skills - Copy just this skill:
cp -r claude-code-skills/daymade-claude-code/claude-md-progressive-disclosurer ~/.claude/skills/ - Confirm the bundled
references/andscripts/folders came along:ls ~/.claude/skills/claude-md-progressive-disclosurer - Restart Claude Code, then ask: "Optimize my CLAUDE.md using progressive disclosure."
- Let it run Step 1 backup first (
cp CLAUDE.md CLAUDE.md.bak.$(date +%Y%m%d_%H%M%S)) before any edits. - Verification steps require
python3— check withpython3 --versionbeforehand, since barepythonis gone on modern macOS.
View source on GitHub ↗License: MIT