Agent Md Refactor

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:

1. Each file should be self-contained for its topic
2. Aim for 3-8 files (not too granular, not too broad)
3. Name files clearly: {topic}.md
4. 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
## OverviewBrief 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:

1. Root file is minimal - Under 50 lines, only universal info
2. Links work - All referenced files exist
3. No contradictions - Instructions are consistent
4. Actionable content - Every instruction is specific
5. Complete coverage - No instructions were lost (unless flagged for deletion)
6. Self-contained files - Each linked file stands alone