---
name: generate-agents-md
description: Use when Codex needs to create, refresh, standardize, audit, or migrate AGENTS.md files or repository-level AI agent instructions, including root or nested guides, project onboarding context, Claude/Copilot/Cursor compatibility, and context-bloat cleanup.
---

# Generate AGENTS.md

## Overview

Create lean, scoped, verifiable `AGENTS.md` files from repository facts. Treat root `AGENTS.md` as always-on context: a map and guardrail, not an encyclopedia.

## Workflow

1. **Scan facts before drafting.** Inspect existing `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, tool rules, manifests, CI, key directories, and docs. Use `rg --files` first. Record unknowns instead of guessing.
2. **Extract only verifiable facts.** Commands must come from files such as `package.json`, `Makefile`, `pyproject.toml`, `Cargo.toml`, `go.mod`, CI workflows, or repo docs. Paths must exist. Omit any command, path, or section that cannot be verified; report the gap in the final response instead of adding placeholders.
3. **Choose the scope model.**
   - Use one root file for small repos with shared commands and conventions.
   - Use root plus child `AGENTS.md` files for monorepos or directories with distinct commands, risks, or conventions.
   - Keep complex task workflows in skills or references, not in always-on `AGENTS.md`.
4. **Draft with the standard contract.** Read `references/agents-md-reference.md` for root and child templates, section guidance, and validation criteria.
5. **Update conservatively.** If `AGENTS.md` already exists, merge rather than replace. Preserve user-written sections unless they are clearly stale or conflict with verified facts. Show conflicts before changing them when possible.
6. **Validate before finishing.** Run the bundled validator when applicable. Use `--local` for child guides, and use `--warnings-as-errors` only when the user or repo explicitly wants strict gating:

```bash
python path/to/generate-agents-md/scripts/validate_agents_md.py --repo /path/to/repo --file /path/to/repo/AGENTS.md
```

Treat validator warnings as review prompts. Do not add unverifiable sections just to silence a warning. Also run repo-native markdown/prose checks if they exist.

## Content Placement

| Content | Put it in |
|---|---|
| Global project purpose, key paths, commands, completion checks, risk boundaries | Root `AGENTS.md` |
| Directory-specific commands, naming, tests, generated files, local risks | Child `AGENTS.md` |
| Long release/migration/audit workflows, repeated procedures, tool recipes | Skill or reference file |
| Human contributor background, product explanation, broad docs | `README.md` or `docs/` |

## Quality Bar

- Keep root files concise, usually under 200 lines.
- Use exact commands, exact paths, and concrete rules.
- Keep recommended sections only when they contain verified content.
- Prefer `Always`, `Ask first`, and `Never` boundaries for risk.
- State user instructions override repo guidance; child files override parent files for their directory.
- Do not include secrets, internal credentials, or unverifiable environment assumptions.
- Do not invent commands, paths, tests, package managers, ownership, or architecture.

## Final Response

Report:

- Files created or updated.
- Evidence used for commands and key paths.
- Validation commands run and results.
- Unknowns or items that need human confirmation.

## Common Mistakes

| Mistake | Fix |
|---|---|
| Root file repeats docs or long workflows | Move detail to child guides, skills, or references |
| Commands are tool names instead of runnable commands | Use exact invocations like `pnpm test` or `make check` |
| Child guide repeats parent rules | Keep only local differences |
| Existing custom guidance is overwritten | Merge and preserve non-conflicting user content |
| Placeholder text remains | Replace with verified facts or write `Unknown` in review notes, not in final guide |
| Validator warnings are treated as required content | Investigate warnings, but omit sections that lack verified facts |
