# claude-md-optimizer

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 · `type=plugin` · Claude Code · ★ 26
- Author: wrsmith108
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/wrsmith108/claude-md-optimizer
- Updated: 2026-06-25
- HTML: https://affpapa.org/en/nevibecode/plugins/claude-md-optimizer

## What it 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.

## Install

### Claude Code (native platform)

**Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add anthropics/claude-plugins-community
```
In the agent chat (not a shell):
```text
/plugin install claude-md-optimizer@claude-community
```

## When to use it
- shrink a `CLAUDE.md` that 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.md` inside the nested-file chain limit
- confirm no content was lost after the rewrite

## Example prompts
- Optimize `CLAUDE.md`, it no longer fits the context window
- \`AGENTS.md` is too long — split it into sub-documents
- Apply progressive disclosure to my agent instruction files

## Similar
- [ponytail](https://affpapa.org/en/nevibecode/plugins/ponytail.md) — plugin · ★ 176443
- [impeccable](https://affpapa.org/en/nevibecode/plugins/impeccable.md) — plugin · ★ 88212
- [last-30-days-skill](https://affpapa.org/en/nevibecode/plugins/last-30-days-skill.md) — plugin · ★ 65508
- [claude-hud](https://affpapa.org/en/nevibecode/plugins/claude-hud.md) — plugin · ★ 28841
- [understand-anything](https://affpapa.org/en/nevibecode/plugins/understand-anything.md) — plugin · ★ 88314
- [mem0](https://affpapa.org/en/nevibecode/plugins/mem0.md) — plugin · ★ 67829

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md