---
name: agents-md-best-practices
description: Refactor AGENTS.md instructions to follow progressive disclosure and AGENTS.md best practices. Use when asked to audit, reorganize, or split AGENTS.md into a minimal root file plus linked docs; includes contradiction checks, essential extraction, grouping, and deletion flags.
---

# Agents MD Best Practices

## Overview

Refactor an AGENTS.md into a minimal root file with links to focused docs, following progressive disclosure. Produce contradictions to resolve, a root essentials set, grouped files, a suggested docs/ structure, and deletion flags.

## Workflow

### 0) Gather inputs

- Ask which AGENTS.md to refactor (path or pasted content).
- Ask whether to apply file changes or draft only.
- Ask where to place new docs/ (default: `docs/agents/`).

### 1) Parse and normalize

- Read the AGENTS.md content.
- Split into individual instructions (one per line/bullet/paragraph).
- Keep original wording; annotate with a short label so you can reference items precisely.

### 2) Find contradictions

- Identify instructions that conflict (opposing directives, incompatible tools, or contradictory constraints).
- Present each contradiction as a pair (or set) and ask which to keep.
- Pause before restructuring until contradictions are resolved.

### 3) Identify essentials for root AGENTS.md

Keep only what belongs in the root file:
- One-sentence project description.
- Package manager if not npm.
- Non-standard build/typecheck commands.
- Anything truly relevant to every single task.

Ask if the user wants any other item in root before finalizing.

### 4) Group the rest into categories

- Cluster remaining instructions into logical, named categories (e.g., TypeScript, Testing, API design, Git workflow, UI, Infra).
- Create a separate markdown file per category.
- Keep categories actionable and scoped; avoid mixed topics.

### 5) Create the file structure

Provide:
- A minimal root `AGENTS.md` with markdown links to the category files.
- Each category file with its relevant instructions.
- A suggested `docs/` folder structure.

Use the template in `references/output-template.md` when helpful.

### 6) Flag for deletion

Identify instructions that are:
- Redundant (agent already knows this).
- Too vague to be actionable.
- Overly obvious (e.g., “write clean code”).

List these separately with a short reason and ask for confirmation before removing.

## Output requirements

- If no contradictions, explicitly say “No contradictions found.”
- Use clear section headings in the response: Contradictions, Root AGENTS.md, New Files, Suggested docs/ Structure, Flags for Deletion.
- Provide file contents in fenced code blocks with filenames.

## Guardrails

- Do not delete or rewrite instructions without user confirmation when conflicts exist or items are flagged.
- Do not expand scope beyond the AGENTS.md content unless the user asks.