agent-md-refactor

To refactor large CLAUDE.md or AGENTS.md files, you extract essential guidelines into a minimal root document and reorganize remaining rules into categorized linked files under a project structure. This progressive-disclosure approach improves readability and speeds up agent startup.

Progressive disclosure for agent instruction files is a structure where a minimal root document contains essential guidelines, while remaining rules are grouped into categorized linked files under a directory like .claude or .cursor to improve maintainability.

Resolving contradictions when cleaning up bloated agent docs involves a staged refactoring workflow that starts with contradiction detection, followed by essentials extraction, categorization, structuring, and pruning to ensure a consistent rule set.

You should split your agent instructions into topic-specific files when your root document exceeds 50 lines, causing readability issues and slowing down agent startup in CLAUDE Code or Cursor workflows.

Yes, you can use this refactoring process for a COPILOT.md file. The skill handles bloated agent instruction files across multiple formats, including AGENTS.md, CLAUDE.md, and COPILOT.md, reorganizing them into a minimal root plus linked documentation.

The best way to organize agent guidelines into a .claude or .cursor directory structure is through a five-phase process: contradiction detection, essentials extraction, grouping, structuring, and deletion flagging, outputting a minimal root file plus topic-specific guidelines.