agent-md-refactor

Overview

Agent MD Refactor is a skill that refactors bloated agent instruction files (AGENTS.md, CLAUDE.md, COPILOT.md, etc.) to follow progressive disclosure principles. It splits monolithic instruction files into organized, linked documentation by extracting essentials for the root file and categorizing the rest into logical files.

Key Features

• 5-Phase Refactoring Process - Analyze (find contradictions), Extract (identify essentials), Categorize (group remaining), Structure (create hierarchy), and Prune (flag redundant content)
• Contradiction Detection - Identifies conflicting instructions like incompatible style guidelines, contradictory workflows, or mutually exclusive patterns before restructuring
• Progressive Disclosure - Keeps only universally applicable rules in the root file (project description, package manager, critical overrides) and links to detailed category files
• Logical Categorization - Organizes instructions into standard categories like typescript.md, testing.md, code-style.md, git-workflow.md, architecture.md, api-design.md
• Essential vs. Non-Essential Separation - Clear criteria for what stays in root (applies to 100% of tasks) versus what gets moved to linked files (language-specific, testing, documentation standards)

Who is this for?

This is for developers whose AGENTS.md, CLAUDE.md, or similar agent instruction files have grown too large and unwieldy. It is ideal for teams that want to reorganize their agent configuration into a maintainable, progressive disclosure structure where the root file stays minimal and detailed instructions live in linked category files.