AGENTS.md Writer

Reply in the user's language. These instructions are in English for token efficiency; that does not dictate the conversation language. If the user writes in Chinese, answer in Chinese — including the review findings and the confirmation prompts.

AGENTS.md is project-level context. Loading and discovery depend on the agent; see the registry. Keep it short: redundant instructions consume context and can compete with important constraints. There is no universal instruction-count or line-count limit that guarantees compliance.

Scope: write only project knowledge that code and configuration do not express: hidden constraints, operational traps, and important decisions with their reasons. Do not reproduce a directory map, script list, dependency versions, or conventions already evident in the repo. Personal preferences belong in the global agent config, not here.

Pick a path

Path A — Write

1. Probe. Never guess.

Verify every command or path that survives content selection before including it.

ls -A                                   # repo root
jq '.scripts' package.json 2>/dev/null  # npm scripts (no jq? read the file — do not truncate with grep -A)
cat pyproject.toml 2>/dev/null          # Python deps and test config
cat Cargo.toml 2>/dev/null              # Rust
find . -maxdepth 1 \( -name Makefile -o -name '*.mk' -o -name 'dev-*.sh' \)
git log --format=%s -20                 # existing commit style

PowerShell equivalents: Get-ChildItem -Force, (Get-Content package.json | ConvertFrom-Json).scripts.

Do not use shell globs to probe. Under zsh, ls *.mk with no match aborts the whole command before ls ever runs, and 2>/dev/null cannot suppress it — the error comes from the shell, not from ls. Use find.

• The project README can be wrong. The filesystem is the source of truth.
• Verify every path as you write it, then re-verify the whole file at the end.
• If you cannot verify a command, do not write it. Mark it as a known gap. Never invent one.
• Discovery is input to your reasoning, not a list to copy into AGENTS.md. Apply Content selection before writing. If nothing qualifies, report that; do not manufacture a file to fill a template.

2. Follow the skeleton

Candidate sections and layering: references/skeleton.md. No section is mandatory; do not add a section merely because it appears in the template.

Blank templates: templates/AGENTS.md.template (English), templates/AGENTS.zh.md.template (Chinese). Delete whole sections that do not apply. Do not leave placeholders behind.

3. Run the checks

Run the bundled script by its absolute skill path, not a project-local ./scripts/ path:

<skill-dir>/scripts/lint-agents-md.sh AGENTS.md
pwsh -File <skill-dir>/scripts/lint-agents-md.ps1 AGENTS.md

The lint covers mechanical checks only. It does not prove rule compliance or functional correctness. Run the rest by hand — see Checklist.

4. Add entry points for other agents

See Entry points. If no AGENTS.md was needed, do not create entry files pointing to a nonexistent file.

Path B — Review

Read only. Do not edit.

1. Read the file, walk the Checklist top to bottom.
2. Verify three things for real:
   • Commands — run the read-only ones. For anything with side effects, check it is at least declared (e.g. present in jq '.scripts' package.json).
   • Paths — test -e each one.
   • Conflicts — against the global config and any other AGENTS.md in the repo.
3. Report: one-line verdict (fine / needs fixes / rewrite), then a list of location → problem → suggested fix.

Do not rewrite the file. The user asked for a diagnosis.

Reviewing many files at once

When the user asks about the whole machine or a whole workspace, locate the files through the filesystem index. Never run an unbounded recursive scan over $HOME.

mdfind -0 -name 'AGENTS.md' | xargs -0 ./scripts/lint-agents-md.sh          # macOS, Spotlight index
mdfind -0 -onlyin ~/work 'kMDItemFSName == "AGENTS.md"' | xargs -0 ...      # scoped
plocate AGENTS.md                                                          # Linux, if indexed
find <dir> -maxdepth 4 -name AGENTS.md                                     # fallback, always scoped

Report as a table — path, line count, error/warning counts — then ask which ones to fix. Fix them one at a time, and for each one list the full path and the exact changes before writing anything.

Path C — Refactor

1. cp AGENTS.md AGENTS.md.bak and tell the user where the backup is.

2. Classify every existing block and show the table before touching anything:

   Destination	What goes there
   Keep in project	Constraints and traps not expressed by code or config; important decisions
   Promote to global	Personal preferences: language, output style, local machine setup
   Push down to subdirectory	Hidden constraints that only concern one module
   Move to a skill / decision document	Multi-step procedures or detailed Event / Decision / Reason records
   Delete	Duplicated repo information, stale content, freshness stamps, one-off requests

3. Show the classification and concrete changes. If the user already authorized this scope, proceed; ask only about unresolved choices that change product behavior or discard still-relevant knowledge.
4. Re-run the checklist. Preserve important decisions in the structured format below; do not discard their reasons while trimming the original discussion.

Content selection

For each candidate rule, ask: can the agent already learn this from code or configuration? If yes, omit it. A directory map can also imply that unlisted paths do not matter; inspect the repository for the current task instead of making a fixed map in AGENTS.md.

Keep a rule when it supplies missing knowledge that changes an action, for example:

• Integration tests silently skip without a local database; a green run can be incomplete.
• A command documented as local maintenance actually targets a shared environment by default.
• A tempting solution was rejected for a compatibility reason the code cannot reveal.

A command or path may appear as part of explaining such a trap, after verification. Do not add an ordinary command catalogue or directory listing around it. Do not copy generic coding advice.

Important decisions

Record important project decisions as Event / Decision / Reason (事件 / 决策 / 原因 in Chinese):

- **Event**: A request can time out after the payment provider accepts it.
- **Decision**: Do not automatically retry payment creation until idempotency is guaranteed.
- **Reason**: A retry can charge twice; the provider does not deduplicate requests.

Use supplied context, existing decision records, or verified history as evidence. Never invent an incident, a rejected option, or its rationale. Ask about a missing reason when it is material. Keep short, currently relevant records here; put detailed records in an existing decision-document location and link them with a reading trigger. Do not preserve every rejected idea. Update or retire obsolete decisions rather than accumulating contradictions. See references/rules-and-decisions.md when reviewing decisions or critical constraints.

Execution mechanisms

For critical constraints, inspect whether tests, lint, CI, or tool permissions actually enforce them. Report the existing mechanism or the gap; AGENTS.md text and a passing document lint are not enforcement. A configured CI check is not proof that merging or releasing is blocked on it. Reuse verified mechanisms. Do not install hooks, create new checks, or change permissions unless that work is authorized. Keep this assessment in the review report; include it in AGENTS.md only when it explains a project-specific trap that the configuration does not reveal.

Writing principles

Length

No hard line limit. The test is: can you delete a line without losing information?

If the root file passes ~200 lines, first check for duplicated code/config information, then move detailed decisions or module-local constraints to their appropriate location. This is a review signal, not a target length; a useful file may contain only a few lines.

Verifiable instructions

Global vs project

Ask whether the rule still holds in a different repo. Yes → global. No → project.

Entry points

Keep one source of truth plus thin entry files — never maintain parallel copies.

Per-agent paths, evidence levels, format caveats, and how to detect installed agents instead of hardcoding a list: references/agent-registry.md.

• Do not use symlinks for project-level entry files. Committed symlinks degrade into plain text files containing a path on Windows and some CI runners. Symlinks are fine for user-level config (~/.claude/, ~/.codex/).
• Check .gitignore does not already exclude CLAUDE.md or GEMINI.md.
• If the user only runs one agent, create only that one entry file.

Checklist

Rows 1–5 are covered by scripts/lint-agents-md.sh / .ps1 as heuristics. Run the rest by hand.

Content that belongs elsewhere

• Runtime prompts or deployment artifacts placed at the repo root as AGENTS.md. The agent will read them as constraints on working in this repo. They are not.
• One-off requests, temporary plans, single-iteration goals. These go in docs/ or an issue.