Agent MD Refactor
Refactor bloated agent instruction files (AGENTS.md, CLAUDE.md, COPILOT.md, etc.) to follow progressive disclosure principles - keeping essentials at root and organizing the rest into linked, categorized files.
Triggers
Use this skill when:
- "refactor my AGENTS.md" / "refactor my CLAUDE.md"
- "split my agent instructions"
- "organize my CLAUDE.md file"
- "my AGENTS.md is too long"
- "progressive disclosure for my instructions"
- "clean up my agent config"
Quick Reference
Process
Phase 1: Find Contradictions
Identify any instructions that conflict with each other.
Look for:
- Contradictory style guidelines (e.g., "use semicolons" vs "no semicolons")
- Conflicting workflow instructions
- Incompatible tool preferences
- Mutually exclusive patterns
For each contradiction found:
## Contradiction Found
**Instruction A:** [quote]
**Instruction B:** [quote]
**Question:** Which should take precedence, or should both be conditional?
Ask the user to resolve before proceeding.
Phase 2: Identify the Essentials
Extract ONLY what belongs in the root agent file. The root should be minimal - information that applies to every single task.
Essential content (keep in root):
NOT essential (move to linked files):
- Language-specific conventions
- Testing guidelines
- Code style details
- Framework patterns
- Documentation standards
- Git workflow details
Phase 3: Group the Rest
Organize remaining instructions into logical categories.
Common categories:
Grouping rules:
- Each file should be self-contained for its topic
- Aim for 3-8 files (not too granular, not too broad)
- Name files clearly:
{topic}.md
- Include only actionable instructions
Phase 4: Create the File Structure
Output structure:
project-root/
├── CLAUDE.md (or AGENTS.md) # Minimal root with links
└── .claude/ # Or docs/agent-instructions/
├── typescript.md
├── testing.md
├── code-style.md
├── git-workflow.md
└── architecture.md
Root file template:
# Project Name
One-sentence description of the project.
## Quick Reference
- **Package Manager:** pnpm
- **Build:** `pnpm build`
- **Test:** `pnpm test`
- **Typecheck:** `pnpm typecheck`
## Detailed Instructions
For specific guidelines, see:
- [TypeScript Conventions](.claude/typescript.md)
- [Testing Guidelines](.claude/testing.md)
- [Code Style](.claude/code-style.md)
- [Git Workflow](.claude/git-workflow.md)
- [Architecture Patterns](.claude/architecture.md)
Each linked file template:
# {Topic} Guidelines
## Overview
Brief context for when these guidelines apply.
## Rules
### Rule Category 1
- Specific, actionable instruction
- Another specific instruction
### Rule Category 2
- Specific, actionable instruction
## Examples
### Good
\`\`\`typescript
// Example of correct pattern
\`\`\`
### Avoid
\`\`\`typescript
// Example of what not to do
\`\`\`
Phase 5: Flag for Deletion
Identify instructions that should be removed entirely.
Delete if:
Output format:
## Flagged for Deletion
| Instruction | Reason |
|-------------|--------|
| "Write clean, maintainable code" | Too vague to be actionable |
| "Use TypeScript" | Redundant - project is already TS |
| "Don't commit secrets" | Agent already knows this |
| "Follow best practices" | Meaningless without specifics |
Execution Checklist
[ ] Phase 1: All contradictions identified and resolved
[ ] Phase 2: Root file contains ONLY essentials
[ ] Phase 3: All remaining instructions categorized
[ ] Phase 4: File structure created with proper links
[ ] Phase 5: Redundant/vague instructions removed
[ ] Verify: Each linked file is self-contained
[ ] Verify: Root file is under 50 lines
[ ] Verify: All links work correctly
Anti-Patterns
Examples
Before (Bloated Root)
# CLAUDE.md
This is a React project.
## Code Style
- Use 2 spaces
- Use semicolons
- Prefer const over let
- Use arrow functions
... (200 more lines)
## Testing
- Use Jest
- Coverage > 80%
... (100 more lines)
## TypeScript
- Enable strict mode
... (150 more lines)
After (Progressive Disclosure)
# CLAUDE.md
React dashboard for real-time analytics visualization.
## Commands
- `pnpm dev` - Start development server
- `pnpm test` - Run tests with coverage
- `pnpm build` - Production build
## Guidelines
- [Code Style](.claude/code-style.md)
- [Testing](.claude/testing.md)
- [TypeScript](.claude/typescript.md)
Verification
After refactoring, verify:
- Root file is minimal - Under 50 lines, only universal info
- Links work - All referenced files exist
- No contradictions - Instructions are consistent
- Actionable content - Every instruction is specific
- Complete coverage - No instructions were lost (unless flagged for deletion)
- Self-contained files - Each linked file stands alone
