Refactor AGENTS.md

\x3Cobjective> Refactor AGENTS.md files so the root file stays small, stable, and broadly useful while detailed guidance moves into focused follow-up docs. The skill helps identify contradictions, separate essentials from bloat, and produce a clearer instruction hierarchy that is easier for agents to follow. \x3C/objective>

\x3Cquick_start>

1. Identify whether the user wants a review, a rewrite proposal, or an in-repo refactor.
2. Read the current AGENTS.md content and classify each instruction as root-essential, topic-specific, conflicting, redundant, vague, or stale.
3. Keep only universal instructions in the root file, move the rest into topic docs, and surface any contradictions before editing. \x3C/quick_start>

\x3Cessential_principles> \x3Cprinciple name="keep-root-minimal"> The root AGENTS.md should contain only what applies to every task: a one-line project description, package manager expectations if non-default, non-standard build or typecheck commands, and truly universal constraints. \x3C/principle>

\x3Cprinciple name="resolve-conflicts-first"> If two instructions disagree, do not silently merge them. Surface the conflict, explain the tradeoff briefly, and ask the user which version to keep before rewriting. \x3C/principle>

\x3Cprinciple name="group-by-purpose"> Move remaining guidance into separate files grouped by topic or behavior, not by author, chronology, or file location. \x3C/principle>

\x3Cprinciple name="delete-bloat"> Flag redundant, vague, self-evident, or outdated instructions for deletion instead of preserving them in a new location. \x3C/principle>

\x3Cprinciple name="prefer_progressive_disclosure"> Keep the root file as a router into narrower guidance. Detail belongs in follow-up docs that are only read when relevant. \x3C/principle> \x3C/essential_principles>

\x3Cintake> Ask the user which mode they want:

1. Review only
2. Propose a rewrite
3. Apply the refactor in the repo

If the user already gave enough context, skip extra questions and go straight to the matching workflow. \x3C/intake>

\x3Crouting> \x3Cmode name="review-only">workflows/audit-agents-md.md\x3C/mode> \x3Cmode name="propose-rewrite">workflows/audit-agents-md.md\x3C/mode> \x3Cmode name="apply-refactor">workflows/refactor-agents-md.md\x3C/mode> \x3C/routing>

\x3Creference_index> All shared guidance lives in references/:

Principles and heuristics: references/principles.md \x3C/reference_index>

\x3Cworkflows_index> \x3Cworkflow name="audit-agents-md.md">Review an AGENTS.md file, classify instructions, and propose a minimal split.\x3C/workflow> \x3Cworkflow name="refactor-agents-md.md">Inspect the repo and rewrite AGENTS.md files in place.\x3C/workflow> \x3C/workflows_index>

\x3Csuccess_criteria> The skill is complete when it can consistently:

• identify contradictions before rewriting
• keep root AGENTS.md content minimal
• split topic-specific guidance into separate docs
• flag redundant, vague, and stale instructions for deletion
• produce a clear proposed file structure or apply it in the repo \x3C/success_criteria>