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

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.
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.
For normal authoring details, use references/normal-authoring.md. Inspect only the sources needed for the claims you will make.
Draft from the smallest applicable template in references/template-selection.md. Prefer assets/agentsmd-minimal.md unless the repo clearly needs a specialized template.
Keep evidence in working notes or the final summary. Add an evidence file only when the repo already owns one or the user asks.
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:

Trigger	Read
Tool, CLI, MCP, API, generated file, migration, schema, or public contract guidance	references/contract-bearing-agentsmd.md
Split, move, nested scopes, stale topology, or ownership handoff	references/topology-and-handoff-guidance.md
Live operations, degraded tools, manual dispatch, stop states, or environment resets	references/degraded-tool-surface.md, references/evidence-invalidation.md
Subagents or delegated review workflows	references/subagent-coordination-patterns.md
Python, TypeScript, other stack, Databricks/Spark, or ML-specific evidence prompts	references/language-specific/python-guidance.md, references/language-specific/typescript-guidance.md, references/language-specific/other-stack-guidance.md, references/domain-specific/databricks-spark.md, references/domain-specific/ml-projects.md
Review-only or judgment-heavy audit	references/manual-audit.md

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

Tool	Use
scripts/analyze_project.py	Stack, config, test, path, and suggestion inventory
scripts/validate_agentsmd.py	Structural validation
scripts/semantic_check_agentsmd.py	Path, command, link, and example validation
scripts/check_agentsmd_templates.py	Skill template and guidance hygiene
scripts/run_agentsmd_fixture_checks.py	Known fixture behavior for validator changes

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

agents-md