agent-md-refactor_skill

Overview

This skill refactors bloated agent instruction files (AGENTS.md, CLAUDE.md, COPILOT.md, etc.) into a minimal root plus linked, topic-focused documents using progressive disclosure. It reduces cognitive load, resolves contradictions, and produces a clear file hierarchy so agents and humans can find actionable guidance quickly.

How this skill works

The skill scans the monolithic instruction file to detect contradictions, redundancies, and non-universal rules. It extracts only universal essentials into a concise root file and groups the rest into 3–8 clearly named topic files with self-contained, actionable rules. It also flags vague or redundant instructions for deletion and emits a verification checklist and file templates.

When to use it

• Your AGENTS.md or CLAUDE.md is overlong or hard to navigate
• You want to apply progressive disclosure to agent instructions
• There are conflicting or duplicated directives in the root file
• You need a maintainable structure for onboarding new agents or contributors
• You want a root file under 50 lines with linked, focused docs

Best practices

• Keep the root file limited to universal rules and critical overrides only
• Group related guidance into 3–8 topic files named {topic}.md
• Make each linked file self-contained, actionable, and example-driven
• Flag vague or redundant lines for deletion rather than burying them
• Resolve contradictions before splitting; ask clarifying questions where needed

Example use cases

• Refactor a 600-line CLAUDE.md into a 30-line root plus five topic files
• Split a mixed-style AGENTS.md into code-style.md, testing.md, and git-workflow.md
• Resolve contradictory style rules (e.g., semicolons vs no semicolons) and document the chosen convention
• Create a .claude/ or docs/agent-instructions/ folder with templates and verification checklist
• Prune outdated or obvious instructions that add noise but no value