claude-md-optimizer — Claude Code plugin: trim CLAUDE.md
A skill that splits bloated agent instruction files into a lean main file plus sub-documents, so context isn't spent on reference material you rarely need.
/plugin marketplace add anthropics/claude-plugins-community
/plugin install claude-md-optimizer@claude-communityWhat claude-md-optimizer does
The plugin scans a repo for three instruction formats: CLAUDE.md, AGENTS.md and .github/copilot-instructions.md. It compares each file against the size target for its format, sorts sections into essential, reference and redundant, then shows a table of what stays inline and what moves out.
Six phases run in order, and nothing is rewritten until you approve the plan. Sub-documents are built with the mechanism each format already supports: @import and .claude/rules/*.md for CLAUDE.md, nested files in subdirectories for AGENTS.md, .github/instructions/NAME.instructions.md for Copilot. A final pass diffs the content before and after to confirm nothing was dropped.
Before touching anything it checks whether the file is encrypted with git-crypt, SOPS or age, and whether a CI script greps it with a regex. Either one means extraction can break your pipeline, so read the plan before approving it. The part that carries the weight is how the reference is written: a synopsis with concrete facts — framework, naming convention, coverage threshold — often answers the agent outright, and the sub-document stays closed.
What it helps with
- shrink a
CLAUDE.mdthat grew past the context budget - move an API reference into a sub-document and keep a synopsis inline
- split rules into
.claude/rules/with path scoping - fit
AGENTS.mdinside the nested-file chain limit - confirm no content was lost after the rewrite
Example prompts for the agent
- Optimize
CLAUDE.md, it no longer fits the context window AGENTS.mdis too long — split it into sub-documents- Apply progressive disclosure to my agent instruction files
How to install claude-md-optimizer
Plugin marketplace
/plugin marketplace add anthropics/claude-plugins-community/plugin install claude-md-optimizer@claude-communityStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about claude-md-optimizer
How do I install claude-md-optimizer in Claude Code?
From the marketplace: run /plugin marketplace add anthropics/claude-plugins-community, then /plugin install claude-md-optimizer@claude-community.
What does claude-md-optimizer do?
It analyzes agent instruction files, separates essential rules from reference material, extracts the reference parts into sub-documents and rewrites the main file with links. You see the plan and approve it before any file changes.
Which instruction file formats does it support?
CLAUDE.md, AGENTS.md and .github/copilot-instructions.md. Detection is automatic, and each format gets its own sub-document mechanism.
