agents-md-optimizer

What this skill does

CLAUDE.md is loaded into every Claude session for the project it belongs to. That means every line is a recurring tax on the context window — paid before any real work starts, across every session, forever. Most CLAUDE.md files drift into bloat: people copy-paste API docs, write step-by-step tutorials, hoard historical state, stack negative "don't do X" rules. The result is a ~2,000-token baseline cost that degrades focus and wastes budget.

The fix is to treat CLAUDE.md like a focused recipe book: essential guidance only, everything else extracted to a location that loads on-demand. This skill does two things:

1. Audit mode — read an existing CLAUDE.md, diagnose what's bloat, and produce a slimmed rewrite plus an extraction plan (what moves where).
2. Author mode — interview about a new project and write a lean CLAUDE.md from scratch using the template.

When to pick a mode

Detect mode from input:

• The user points at an existing file, or one is visible in context → audit mode.
• The user wants a fresh CLAUDE.md for a new or undocumented project → author mode.
• Both (they showed a file but also want a rewrite philosophy applied to a second project) → run audit first, carry the principles into the author pass.