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
1---2name: agents-md3description: Use when the requested deliverable includes creating, reviewing, moving, splitting, or updating a repository AGENTS.md; produces scoped repo guidance. Do not trigger for standalone skills, prompts, non-AGENTS instruction files, READMEs, changelogs, or architecture docs.4---5
6# Manage AGENTS.md
7
8`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.
9
10## When to Use
11
12- Create, update, review, split, move, or repair a repository `AGENTS.md`.
13- Capture verified local commands, repo contracts, path ownership, or recurring agent mistakes.
14- Convert repo evidence into rules that future agents can follow.
15
16## When NOT to Use
17
18- Standalone skills, prompts, global instructions, READMEs, architecture docs, changelogs, or runbooks.
19- Broad documentation rewrites where `AGENTS.md` is not an explicit deliverable.
20- Aspirational process guidance that is not supported by current repo evidence.
21
22## Modes
23
24- **patch**: small text fix, typo, stale path, or narrow rule change. Inspect the affected section and evidence only.
25- **create**: no suitable `AGENTS.md` exists. Run the analyzer, sample source/config/docs, then draft the smallest useful file.
26- **update**: existing file needs new or corrected guidance. Preserve valid rules, remove stale or duplicated material, and add only evidenced changes.
27- **split/move**: scope boundaries are changing. Inspect existing root and nested files, then use [references/topology-and-handoff-guidance.md](references/topology-and-handoff-guidance.md).
28- **review**: do not edit unless asked. Return findings by severity with evidence and residual risk.
29- **exhaustive**: monorepos, contract-heavy repos, safety-sensitive guidance, operational handoffs, major topology changes, or unclear evidence.
30
31## Workflow
32
331. 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.
342. 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.
353. For normal authoring details, use [references/normal-authoring.md](references/normal-authoring.md). Inspect only the sources needed for the claims you will make.
364. Draft from the smallest applicable template in [references/template-selection.md](references/template-selection.md). Prefer [assets/agentsmd-minimal.md](assets/agentsmd-minimal.md) unless the repo clearly needs a specialized template.
375. Keep evidence in working notes or the final summary. Add an evidence file only when the repo already owns one or the user asks.
386. 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>`.
39
40## Rule Quality Rubric
41
42Keep a rule only when it is:
43
44- **specific**: names actual paths, commands, contracts, or local conventions.
45- **current**: supported by live files or user-provided current facts.
46- **scoped**: applies to this `AGENTS.md` directory tree.
47- **behavioral**: changes what an agent should do.
48- **evidence-backed**: traceable to inspected repo evidence.
49- **safe**: avoids secrets, unauthorized access, destructive commands, and production execution.
50- **non-duplicative**: does not restate global instructions, language basics, or README content.
51- **concise**: short enough to scan during normal coding work.
52
53## Escalation Matrix
54
55Load extra references only when the task needs them:
56
57| Trigger | Read |
58|---------|------|
59| Tool, CLI, MCP, API, generated file, migration, schema, or public contract guidance | [references/contract-bearing-agentsmd.md](references/contract-bearing-agentsmd.md) |
60| Split, move, nested scopes, stale topology, or ownership handoff | [references/topology-and-handoff-guidance.md](references/topology-and-handoff-guidance.md) |
61| Live operations, degraded tools, manual dispatch, stop states, or environment resets | [references/degraded-tool-surface.md](references/degraded-tool-surface.md), [references/evidence-invalidation.md](references/evidence-invalidation.md) |
62| Subagents or delegated review workflows | [references/subagent-coordination-patterns.md](references/subagent-coordination-patterns.md) |
63| Python, TypeScript, other stack, Databricks/Spark, or ML-specific evidence prompts | [references/language-specific/python-guidance.md](references/language-specific/python-guidance.md), [references/language-specific/typescript-guidance.md](references/language-specific/typescript-guidance.md), [references/language-specific/other-stack-guidance.md](references/language-specific/other-stack-guidance.md), [references/domain-specific/databricks-spark.md](references/domain-specific/databricks-spark.md), [references/domain-specific/ml-projects.md](references/domain-specific/ml-projects.md) |
64| Review-only or judgment-heavy audit | [references/manual-audit.md](references/manual-audit.md) |
65
66## Final Response
67
68For edit modes, include changed files, rules added/changed/removed, evidence sources sampled, validation commands and results, and residual risks.
69
70For 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.
71
72## Deterministic Tools
73
74| Tool | Use |
75|------|-----|
76| [scripts/analyze_project.py](scripts/analyze_project.py) | Stack, config, test, path, and suggestion inventory |
77| [scripts/validate_agentsmd.py](scripts/validate_agentsmd.py) | Structural validation |
78| [scripts/semantic_check_agentsmd.py](scripts/semantic_check_agentsmd.py) | Path, command, link, and example validation |
79| [scripts/check_agentsmd_templates.py](scripts/check_agentsmd_templates.py) | Skill template and guidance hygiene |
80| [scripts/run_agentsmd_fixture_checks.py](scripts/run_agentsmd_fixture_checks.py) | Known fixture behavior for validator changes |
81
82## References
83
84- [references/tool-contracts.md](references/tool-contracts.md) and [references/template-selection.md](references/template-selection.md) - helper CLI contracts, modes, and templates
85- [assets/agentsmd-minimal.md](assets/agentsmd-minimal.md), [assets/agentsmd-contract-bearing.md](assets/agentsmd-contract-bearing.md), [assets/agentsmd-operational.md](assets/agentsmd-operational.md), [assets/agentsmd-full.md](assets/agentsmd-full.md) - starter templates
86- [assets/example-validated-agentsmd.md](assets/example-validated-agentsmd.md), [assets/example-contract-bearing-agentsmd.md](assets/example-contract-bearing-agentsmd.md), [assets/example-operational-agentsmd.md](assets/example-operational-agentsmd.md), [assets/writing-tips.md](assets/writing-tips.md) - compact examples
om-scogo