ai-agents-md · diff
git:20260903.512b20d to git:20260910.f2e5ee1
55 added, 11 removed. Audit A to A.
---
name: ai-agents-md
description: >-
- Creates and maintains the AGENTS.md a repository owes its coding agents, following the
- agents.md convention (https://agents.md/). Decides root-only versus nested AGENTS.md files
- from the repo's real shape, interviews the tree (not the user) for build/test/lint commands,
- and writes only what an agent cannot deduce from the code. Also the in-session maintenance
- path: a governed agent MAY edit AGENTS.md directly (blueprint §9.2 — it is not sacred) when
- the repo's real state made a rule stale. Trigger for "create AGENTS.md", "update AGENTS.md",
- "the agent ignores our conventions", "set up agent instructions", "edit AGENTS.md".
- Not for runtime agent contracts (goals, gates, budgets) — use /ai-goal. Not for
- documentation users read — use /ai-write.
+ Creates, audits and maintains the AGENTS.md a repository owes its coding agents, following
+ the agents.md convention (https://agents.md/). Decides root-only versus nested AGENTS.md
+ files from the repo's real shape, interviews the tree (not the user) for build/test/lint
+ commands, and writes only what an agent cannot deduce from the code. Audits a set that
+ already exists: a rule the code states, a child repeating its parent, a command that no
+ longer runs, a zone with no route in. Also the in-session maintenance path: a governed agent
+ MAY edit AGENTS.md directly (blueprint §9.2 — it is not sacred) when the repo's real state
+ made a rule stale. Trigger for "create AGENTS.md", "update AGENTS.md", "audit AGENTS.md",
+ "split AGENTS.md", "AGENTS.md is too long", "the agent reads the wrong file", "the agent
+ ignores our conventions", "set up agent instructions", "edit AGENTS.md". Not for runtime
+ agent contracts (goals, gates, budgets) — use /ai-goal. Not for documentation users read —
+ use /ai-write.
license: Apache-2.0
---
# AGENTS.md for this repository, sized to its shape
`AGENTS.md` is the file coding agents read before working in a repo (https://agents.md/ and
https://github.com/agentsmd/agents.md). It is instructions for the agent, in the open, owned
by the team. ai-engineering governs the format; your repo owns the content.
## One file or many
The default is ONE `AGENTS.md` at the repository root: most agents read the nearest file up
the tree, so a single root file covers every package. Add nested files only when a
subproject genuinely needs different instructions — monorepos where packages have different
toolchains, test runners, or review rules. The test is mechanical:
- One toolchain, one test command repo-wide → root only.
- Two or more packages with different commands, lint rules, or conventions → one root file
with what is shared, one nested file per divergent package with what differs.
- A nested file must not repeat its parents: repetition drifts. State only the delta.
Say the decision out loud when you write the file: "single root AGENTS.md" or "root + N
nested, one per package that diverges".
## What goes in (and what never does)
Sections that earn their place, in this order when present:
1. **Security** — hook-skip and linter-silence prohibitions, secrets/personal-data rules.
2. **Code style** — only the rules the linter cannot check (the linter checks its own).
3. **Build and test commands** — the exact commands, detected from the tree (package.json
scripts, Cargo.toml, go.mod, pyproject.toml...), never from memory.
4. **Workflow** — the definition of done: green gate before "done", status conventions.
5. **Pull requests** — title format, pre-commit checks, test expectations.
6. **Session hygiene** — context-economy conventions the repo expects.
Never include: anything `--help` or a config file already says; a tutorial; rules a
newcomer can deduce from one look at the tree. Anti-drift rule: if a line becomes obvious
from reading the code, delete the line.
+ Two more tests decide a line. **Enforcement**: an always or a never names the mechanism that
+ holds it (a hook, a test, a CI job), because an unenforced rule rots. **Cost**: the root file
+ loads on every turn, so overflow moves behind a pointer in a nested file or a reference, never
+ into the always-loaded one; `doctor` warns once the root passes 80 lines.
+
## Steps
1. Interview the tree: manifests, CI files, existing lint configs, the test layout, README.
Every command you write must exist — run it or read it, do not recall it.
2. Decide root-only versus nested from the shape test above.
3. Write the file (or the deltas) against the section order. One idea per line. If the
- repository already has an AGENTS.md, edit it — never start a parallel one.
+ repository already has an AGENTS.md, edit it — never start a parallel one. Every
+ `AGENTS.md` gets its sibling `CLAUDE.md`: a relative symlink to `AGENTS.md` in the same
+ directory, the mechanism `ai-eng init` uses, or a one-line `@AGENTS.md` import where the
+ OS refuses a symlink.
4. Verify every named command by running it. A command that fails as written is a finding
against the file, not against the repo.
5. Hand the prose to /ai-write when the repository has adopted the ai-engineering writing
standard — the same one-idea-per-sentence, verify-against-tree discipline applies.
+ ## Auditing a set that already exists
+
+ A repo that already has guidance has a set, not a file: the root, whatever nested files grew
+ with it, and the instruction files other tools read. Audit the set against the tree before
+ changing any of it.
+
+ 1. Inventory, from the tree and never from memory: every file named `AGENTS.md` under the root,
+ and every instruction file the repo ships today (`CLAUDE.md`, a Cursor rules directory, a
+ Copilot instructions file). State the shape in one sentence: root only, or root plus N
+ nested.
+ 2. Judge every line of every file by four findings, and quote the line when you report one:
+ - **Deduced**: the code, a manifest or CI already states it. It goes.
+ - **Duplicated**: a nested file repeats its parent, or the parent carries detail only one
+ subtree needs. It moves down, or it goes.
+ - **Dead**: a named command no longer runs as written. Run it; the failure is the finding.
+ - **Unrouted**: a zone an agent must work in with nothing saying what to read and what to
+ skip. Missing guidance is a finding too, not a blank.
+ 3. Decide the shape with the test above, out loud. A repo that does not diverge keeps one file,
+ even if it arrived with four.
+ 4. **Stop and propose**: the findings, and the target set file by file (the count, the
+ sections, the lines that go, the lines that move where). Write nothing before the answer.
+ These files are prose the team owns; the audit earns the edit by showing what it changes.
+ 5. Write the set: edit the root in place, create or trim the nested files, delta only. Never a
+ parallel file under another name, and never a section that both a parent and a child carry.
+ 6. Mirror and align: apply the sibling rule from Steps to every file the audit writes or keeps.
+ An instruction file another tool reads that states what the set no longer says gets the same
+ edit, or is named as a finding and left alone.
+ 7. Verify the result: every command in the set runs as written, no line is carried by both a
+ parent and a child, and every file follows the section order above.
+
## Done when
- Every command in the file runs as written.
- The file states only what the tree cannot tell the agent.
- Root-only or root+nested is a decision the tree shape justifies, and nested files carry
deltas only.
- - The file lives at the root (and only where needed below), named exactly `AGENTS.md`.
+ - The file lives at the root (and only where needed below), named exactly `AGENTS.md`, with its
+ sibling `CLAUDE.md` resolving to it.
+ - A repo that arrived with a set was audited, not overwritten: every surviving line is a
+ decision the tree justifies, and nothing was written before the proposal was approved.
## Keeping it alive from inside a governed session
`AGENTS.md` is a prose contract the team owns — NOT machinery. A governed agent may edit it
in-session (blueprint §9.2: it is not sacred); `self-protect` only denies the wiring
(`.ai-engineering/`, surface settings, git hooks, the global canon, an approved spec.html).
Edit it when the repo's real state made a rule stale, never to bend a rule this task dislikes:
1. The trigger is evidence: a rule that no longer matches the tree (a command that fails, a
convention the code now states by itself, a workflow the team changed). Say what you
observed, at file:line, before touching the file.
2. Edit, never rewrite: change the stale lines, keep the section order, one idea per line.
The status convention and the Security section are not yours to delete.
3. Every edit lands as a visible diff (git diff) and survives review — the file is committed
like any other source. If the change is contentious, propose it instead of pushing it.
4. After editing, run `ai-eng doctor`: the anti-drift check flags any rule the code now
states — delete that line while you are there.
## The ai-engineering seam
1. `ai-eng init` plants this file once (never overwritten by update — 3-way diff if you
edited it). This skill is how you rewrite it deliberately.
2. The governed agent edits it in-session when the tree moved on (section above);
`self-protect` guards the wiring instead — the file is prose the team owns.
3. `ai-eng doctor` checks the anti-drift rule: a rule that the code now states is flagged
as removable.
4. Keep the governed sections (Security, Workflow status convention) aligned with the
guards: the guards enforce `--no-verify` and linter silencing at hook time; the file
tells the agent before the hook has to.
Source: the agents.md convention (https://agents.md/, https://github.com/agentsmd/agents.md)
plus the sample layouts published there; adapted as the ai-engineering authoring skill.