claude-md-progressive-disclosurer_skill

Overview

This skill optimizes CLAUDE.md files using a progressive disclosure architecture to maximize information efficiency, readability, and maintainability. It enforces a two-level split: a compact, high-signal Level 1 loaded every session and on-demand Level 2 references. The goal is to keep high-frequency commands and code patterns immediately available while moving verbose SOPs, edge cases, and history to referenced files with clear trigger conditions.

How this skill works

The skill analyzes the CLAUDE.md content and classifies each section into Level 1 (always-loaded) or Level 2 (on-demand reference). It preserves original content when moving sections to Level 2, adds trigger-condition summaries and multiple entry points, and inserts an "information recording" principle at the top to prevent future bloat. It also runs a checklist-driven verification to ensure no content is silently deleted and that all references exist.

When to use it

• You want to reduce cognitive overload in CLAUDE.md without losing information.
• Information is duplicated across files or appears in multiple places.
• LLMs repeatedly ignore rules or rederive common code patterns.
• Preparing the project CLAUDE.md for team use or onboarding.
• Before large documentation refactors to avoid accidental deletions.

Best practices

• Keep core commands, code patterns, diagnostics, and hard rules in Level 1 for direct copying.
• Move long SOPs, edge-case troubleshooting, and history to docs/references as exact copies—don't compress during the move.
• Every Level 2 reference must include concise trigger conditions and a short summary in Level 1.
• Provide multiple entry points (index at top, 'modify-before' table in middle, and trigger index at end).
• Never use line count as an optimization metric or mention line-count changes in summaries.

Example use cases

• Refactor a bloated project CLAUDE.md so daily commands and copy-paste code remain front-and-center.
• Fix repeated LLM failures by surfacing ironclad 'do-not-do' rules and direct code examples in Level 1.
• Archive detailed deployment SOPs and edge-case debugging steps into docs/references while adding trigger hints.
• Onboard a new teammate: give them a short Level 1 they can use immediately and pointed Level 2 docs for deeper tasks.