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

## 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:

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

---

Agent MD Refactor

A Claude Code skill that transforms bloated agent instruction files into clean, organized documentation using progressive disclosure principles.

Based on https://x.com/mattpocockuk/status/2012906065856270504 (Matt Pocock's Prompt Idea)

Purpose

Over time, agent instruction files like CLAUDE.md, AGENTS.md, or COPILOT.md tend to grow into unwieldy documents containing hundreds of lines of mixed instructions. This creates several problems:

• Context waste: Every task loads the entire file, even when most instructions are irrelevant
• Maintenance burden: Finding and updating specific instructions becomes difficult
• Contradictions: Conflicting guidelines accumulate without being noticed
• Signal-to-noise ratio: Important rules get buried among obvious or vague statements

This skill solves these problems by applying progressive disclosure - keeping only essential, universal instructions in the root file while organizing everything else into focused, linked documentation files.

When to Use

Use this skill when you need to clean up agent instruction files. Common trigger phrases include:

• "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"

Good candidates for refactoring:

• Root agent files exceeding 50-100 lines
• Files mixing multiple unrelated topics (testing, code style, architecture, etc.)
• Documents that have grown organically without structure
• Files containing contradictory or redundant instructions

How It Works

The skill follows a systematic 5-phase process:

Phase 1: Find Contradictions

Before restructuring, the skill identifies conflicting instructions that need resolution. Examples include contradictory style guidelines ("use semicolons" vs "no semicolons") or incompatible workflow instructions. Each contradiction is surfaced with a question for the user to resolve.

Phase 2: Identify the Essentials

Extracts only what truly belongs in the root file - information that applies to every single task:

Phase 3: Group the Rest

Organizes remaining instructions into logical categories like:

• typescript.md - Type patterns, strict mode rules
• testing.md - Test frameworks, coverage, mocking
• code-style.md - Formatting, naming, structure
• git-workflow.md - Commits, branches, PRs
• architecture.md - Patterns, folder structure

Phase 4: Create the File Structure

Generates the new file hierarchy with properly linked documentation:

project-root/
├── CLAUDE.md              # Minimal root with links
└── .claude/               # Categorized instructions
    ├── typescript.md
    ├── testing.md
    ├── code-style.md
    └── architecture.md

Phase 5: Flag for Deletion

Identifies instructions that should be removed entirely:

• Redundant: "Use TypeScript" in a TypeScript project
• Too vague: "Write clean code" without specifics
• Overly obvious: "Don't introduce bugs"
• Default behavior: "Use descriptive variable names"
• Outdated: References to deprecated APIs

Key Features

• Contradiction detection: Surfaces conflicting instructions before restructuring
• Intelligent categorization: Groups related instructions into logical files
• Root file minimization: Targets under 50 lines for the main file
• Deletion recommendations: Identifies instructions wasting context tokens
• Template-driven output: Consistent structure across all generated files
• Link verification: Ensures all references between files are valid

Usage Examples

Basic Refactoring

User: refactor my CLAUDE.md

Claude: I'll analyze your CLAUDE.md file and refactor it using progressive
disclosure principles...

Specific File

User: my AGENTS.md is too long, can you split it up?

Claude: I'll review your AGENTS.md and organize it into focused, linked files...

After a Project Grows

User: organize my agent config - it's gotten out of control

Claude: I'll apply the 5-phase refactoring process to clean up your
agent instructions...

Output

After running the skill, you get:

Minimal root file (~50 lines or less):

# Project Name

One-sentence description of the project.

## Quick Reference

- **Package Manager:** pnpm
- **Build:** `pnpm build`
- **Test:** `pnpm test`

## Detailed Instructions

- [TypeScript Conventions](.claude/typescript.md)
- [Testing Guidelines](.claude/testing.md)
- [Code Style](.claude/code-style.md)

Organized linked files with consistent structure:

# Testing Guidelines

## Overview
Brief context for when these guidelines apply.

## Rules

### Unit Tests
- Specific, actionable instruction
- Another specific instruction

## Examples

### Good
[code example]

### Avoid
[code example]

Deletion report:

## Flagged for Deletion

| Instruction | Reason |
|-------------|--------|
| "Write clean, maintainable code" | Too vague to be actionable |
| "Use TypeScript" | Redundant - project is already TS |

Best Practices

Before Refactoring

1. Commit current state - Have a clean git state so you can review changes 2. Identify your goals - Know what problems you want to solve 3. Gather all instruction files - Some projects have instructions scattered across multiple locations

During Refactoring

1. Resolve contradictions first - Do not proceed until conflicts are addressed 2. Be aggressive about root minimization - When in doubt, move it out 3. Aim for 3-8 linked files - Not too granular, not too broad 4. Delete liberally - Vague instructions waste tokens without providing value

After Refactoring

1. Verify all links work - Test that referenced files exist 2. Check for lost instructions - Ensure nothing important was dropped 3. Test with real tasks - Run a few typical tasks to verify the agent can find needed instructions

Anti-Patterns to Avoid

Verification Checklist

After refactoring, verify:

• [ ] Root file is under 50 lines
• [ ] Root contains ONLY universal information
• [ ] All links to sub-files work correctly
• [ ] No contradictions remain between files
• [ ] Every instruction is specific and actionable
• [ ] No instructions were lost (unless intentionally deleted)
• [ ] Each linked file is self-contained for its topic

License

MIT