Claude Md Optimizer

claude-md-optimizer

A Claude Code skill that optimizes oversized agent instruction files using progressive disclosure. Handles **CLAUDE.md** (Claude Code), **AGENTS.md** (OpenAI Codex / GitHub Copilot agents), and **copilot-instructions.md** (GitHub Copilot). Auto-detects all three formats, analyzes content tiers, creates sub-documents using each format's native mechanism, and rewrites the main file — with zero information loss.

The Problem

Agent instruction files grow organically as projects mature. They accumulate troubleshooting guides, deployment commands, API references, and configuration examples alongside the essential rules needed every session. Since these files are loaded into every AI session as context, oversized files waste the context window on content that's only needed occasionally — and for CLAUDE.md, Anthropic explicitly warns that adherence degrades above 200 lines.

Projects with 6+ months of development commonly reach 800–1,500+ lines.

Supported Formats

Format	Primary Location	Target Size	Native Sub-Doc Mechanism
CLAUDE.md	./CLAUDE.md or ./.claude/CLAUDE.md	<200 lines	@import syntax; .claude/rules/*.md
AGENTS.md	./AGENTS.md (hierarchical)	<32 KiB chain (Codex default)	Nested AGENTS.md in subdirectories
copilot-instructions.md	.github/copilot-instructions.md	~100 lines	.github/instructions/NAME.instructions.md

How It Works

The skill uses a 6-phase guided workflow:

1. Detect & Analyze — Auto-scan the repo for all three file types; report sizes vs. format targets; parse and categorize sections as Essential, Reference, or Redundant
2. Detect Constraints — Check for git-crypt/SOPS/age encryption; identify format-native sub-doc mechanisms; scan for CI scripts that regex-scan the file
3. Plan — Present a categorization table showing what stays inline vs. what gets extracted (and where)
4. *Review