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 surf