Agent MD Refactor Engine

A Claude Code skill for refactoring bloated agent instruction files (AGENTS.md, CLAUDE.md, COPILOT.md, etc.) using progressive disclosure principles. Transforms monolithic instruction files into a well-organized hierarchy that keeps essentials at root level and pushes details into topic-specific files.

When to Use This Skill

Choose Agent MD Refactor when:

• Your CLAUDE.md or AGENTS.md has grown beyond 500 lines
• Agent performance has degraded due to excessive instruction context
• You want to organize instructions into a maintainable hierarchy
• You need to split monolithic instructions into topic-specific files
• You want to follow progressive disclosure for agent instructions

Consider alternatives when:

• You're creating a new CLAUDE.md from scratch (use project setup best practices)
• You need prompt engineering for API calls (use a prompt engineering skill)
• You want to build a multi-agent system (use an agent platform skill)

Quick Start

Copy
# Install the skill
claude install agent-md-refactor-engine

# Analyze current instruction file
claude "Analyze my CLAUDE.md for bloat. How many lines? What can be extracted?"

# Refactor into hierarchy
claude "Refactor my CLAUDE.md into a progressive disclosure structure: root essentials + topic-specific reference files"

# Optimize for context window
claude "My AGENTS.md is 2,000 lines. Reduce it to under 200 lines while preserving all instructions in linked files"

Core Concepts

Progressive Disclosure Hierarchy

Level	Contents	Max Length
Root (CLAUDE.md)	Critical rules, project context, navigation	100-200 lines
Topic Files	Detailed guidelines per domain	200-400 lines each
Reference Files	Exhaustive documentation, examples	Unlimited

File Organization

project/
├── CLAUDE.md (root — essentials only)
│   → Project overview
│   → Critical rules (5-10 most important)
│   → File navigation guide
│   → @import references to topic files
│
├── .claude/
│   ├── code-style.md → Coding conventions, formatting
│   ├── architecture.md → System design, patterns
│   ├── testing.md → Test conventions, coverage rules
│   ├── git.md → Commit format, branch strategy
│   ├── deployment.md → Deploy process, environments
│   └── api.md → API conventions, error handling
│
└── docs/ (reference only, not in context)
    ├── onboarding.md → New developer guide
    └── decisions/ → ADRs and decision logs

Refactoring Rules

Rule	Before	After
Extract by topic	All rules in one file	Topic-specific files
Keep root lean	2,000-line CLAUDE.md	150-line CLAUDE.md
Link, don't duplicate	Same rule in 3 places	One source of truth
Prioritize essentials	Everything is equal priority	Top 10 rules at root
Use cross-references	Flat list of rules	"See .claude/testing.md for details"

Configuration

Parameter	Type	Default	Description
source_file	string	"CLAUDE.md"	File to refactor
max_root_lines	number	200	Maximum lines in root file
output_dir	string	".claude"	Directory for extracted topic files
format	string	"markdown"	Output format: markdown, yaml
preserve_originals	boolean	true	Keep backup of original files

Best Practices

1. The root file should answer "what matters most?" — Read your CLAUDE.md and ask: if the agent could only see 20 lines, which 20 would matter most? Those go at root level. Everything else is extracted.

2. Group instructions by when they're needed — Testing guidelines are only relevant when writing tests. API conventions matter only when touching APIs. Put these in topic files that the agent references on demand.

3. Remove duplicates ruthlessly — Bloated instruction files often repeat the same rule in different phrasings. Pick the clearest version, put it in one place, and link to it from other contexts.

4. Use imperative language — "Use TypeScript strict mode" is clearer than "We prefer to use TypeScript strict mode when possible." Instructions should be direct commands, not suggestions.

5. Review quarterly — Instructions accumulate over time. Schedule quarterly reviews to remove outdated rules, consolidate similar instructions, and ensure the hierarchy still makes sense as the project evolves.

Common Issues

Agent ignores extracted files — The root file must clearly reference topic files with specific triggers: "When writing tests, follow .claude/testing.md." Without clear triggers, the agent won't know when to consult topic files.

Too many topic files — Don't extract every paragraph into its own file. Aim for 4-8 topic files that cover broad domains. Too many small files make navigation harder, not easier.

Refactoring loses important context — Before refactoring, catalog every instruction and ensure it appears in the new structure. Use a checklist to verify nothing was dropped during extraction.