ai-agents-md
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
arcasilesgroup · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add arcasilesgroup/ai-engineering --skill ai-agents-md技能说明
name: ai-agents-md description: >- 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:
- Security — hook-skip and linter-silence prohibitions, secrets/personal-data rules.
- Code style — only the rules the linter cannot check (the linter checks its own).
- Build and test commands — the exact commands, detected from the tree (package.json scripts, Cargo.toml, go.mod, pyproject.toml...), never from memory.
- Workflow — the definition of done: green gate before "done", status conventions.
- Pull requests — title format, pre-commit checks, test expectations.
- 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
- 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.
- Decide root-only versus nested from the shape test above.
- 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. Every
AGENTS.mdgets its siblingCLAUDE.md: a relative symlink toAGENTS.mdin the same directory, the mechanismai-eng inituses, or a one-line@AGENTS.mdimport where the OS refuses a symlink. - Verify every named command by running it. A command that fails as written is a finding against the file, not against the repo.
- 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.
- Inventory, from the tree and never from memory: every file named
AGENTS.mdunder 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. - 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.
- Decide the shape with the test above, out loud. A repo that does not diverge keeps one file, even if it arrived with four.
- 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.
- Write the set: edit the root in place, create or trim the nested files, delta only. Never a parallel file under another name, a