Refactor AGENTS.md

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.

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.

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.

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.

Move remaining guidance into separate files grouped by topic or behavior, not by author, chronology, or file location.

Flag redundant, vague, self-evident, or outdated instructions for deletion instead of preserving them in a new location.

Keep the root file as a router into narrower guidance. Detail belongs in follow-up docs that are only read when relevant.

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.

workflows/audit-agents-md.md

workflows/audit-agents-md.md

workflows/refactor-agents-md.md

All shared guidance lives in references/:

Principles and heuristics: references/principles.md

Review an AGENTS.md file, classify instructions, and propose a minimal split.

Inspect the repo and rewrite AGENTS.md files in place.

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