Manage AGENTS.md

Manage AGENTS.md

AGENTS.md gives coding agents scoped, current, repo-specific instructions. It is not a README, runbook, architecture doc, changelog, tutorial, or evidence log. Good guidance is evidence-backed, concise, scoped to the file's directory tree, and behavioral: it tells agents what to do differently in this repository.

When to Use

• Create, update, review, split, move, or repair a repository AGENTS.md.
• Capture verified local commands, repo contracts, path ownership, or recurring agent mistakes.
• Convert repo evidence into rules that future agents can follow.

When NOT to Use

• Standalone skills, prompts, global instructions, READMEs, architecture docs, changelogs, or runbooks.
• Broad documentation rewrites where AGENTS.md is not an explicit deliverable.
• Aspirational process guidance that is not supported by current repo evidence.

Modes

• patch: small text fix, typo, stale path, or narrow rule change. Inspect the affected section and evidence only.
• create: no suitable AGENTS.md exists. Run the analyzer, sample source/​config/​docs, then draft the smallest useful file.
• update: existing file needs new or corrected guidance. Preserve valid rules, remove stale or duplicated material, and add only evidenced changes.
• split/​move: scope boundaries are changing. Inspect existing root and nested files, then use references/​topology-and-handoff-guidance.md.
• review: do not edit unless asked. Return findings by severity with evidence and residual risk.
• exhaustive: monorepos, contract-heavy repos, safety-sensitive guidance, operational handoffs, major topology changes, or unclear evidence.

Workflow

1. Pick the mode and target scope. Read the nearest existing AGENTS.md, nested AGENTS.md files that may overlap, and git status --short when available.
2. For create, update, split/​move, or exhaustive modes, run python <skill-root>/​scripts/​analyze_project.py --repo-root <target-repo> --format json. Treat it as a sampling guide, not authority.
3. For normal authoring details, use references/​normal-authoring.md. Inspect only the sources needed for the claims you will make.
4. Draft from the smallest applicable template in references/​template-selection.md. Prefer assets/​agentsmd-minimal.md unless the repo clearly needs a specialized template.
5. Keep evidence in working notes or the final summary. Add an evidence file only when the repo already owns one or the user asks.
6. Validate with python <skill-root>/​scripts/​validate_agentsmd.py --repo-root <target-repo> --agents-file <target-agents-file> --mode <quick|standard|exhaustive> and python <skill-root>/​scripts/​semantic_check_agentsmd.py --repo-root <target-repo> --agents-file <target-agents-file>.

Rule Quality Rubric

Keep a rule only when it is:

• specific: names actual paths, commands, contracts, or local conventions.
• current: supported by live files or user-provided current facts.
• scoped: applies to this AGENTS.md directory tree.
• behavioral: changes what an agent should do.
• evidence-backed: traceable to inspected repo evidence.
• safe: avoids secrets, unauthorized access, destructive commands, and production execution.
• non-duplicative: does not restate global instructions, language basics, or README content.
• concise: short enough to scan during normal coding work.

Escalation Matrix

Load extra references only when the task needs them:

Final Response

For edit modes, include changed files, rules added/​changed/​removed, evidence sources sampled, validation commands and results, and residual risks.

For review mode, lead with findings ordered by severity. Each finding needs the affected AGENTS.md section or line, supporting repo evidence, why it matters, and the recommended fix. Then list open questions, test/​validation gaps, and a brief summary only after findings.

Deterministic Tools

References

• references/​tool-contracts.md and references/​template-selection.md - helper CLI contracts, modes, and templates
• assets/​agentsmd-minimal.md, assets/​agentsmd-contract-bearing.md, assets/​agentsmd-operational.md, assets/​agentsmd-full.md - starter templates
• assets/​example-validated-agentsmd.md, assets/​example-contract-bearing-agentsmd.md, assets/​example-operational-agentsmd.md, assets/​writing-tips.md - compact examples