Defame1297
e42c055294
Description 960 -> 244 chars, body 470 -> 452 words, Gotchas 36% -> 22%. Both composition notes move to README.md, which already carried them. Four of five Gotchas were paraphrases of the step below them and were deleted with their force folded back into that step. A clean-context audit overturned the fifth deletion: the provider-file prohibition was strictly broader than Step 4, so it was never a paraphrase, and Step 4's 'don't rewrite it yourself' is attached to the if-duplicates branch. With Write and Edit granted, a provider file that was merely stale had nothing forbidding an edit. Restored as an unconditional Gotcha, read before any step writes. Also restores a concrete indirect trigger. The retrofit had replaced two with the meta-statement 'even when they don't name the file', which claims an indirect trigger exists rather than being one -- and users asking to document a repo for AI tools have no reason to know the filename. Refs #99
3.4 KiB
name, description, allowed-tools, metadata
| name | description | allowed-tools | metadata | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| agentsmd-author | Use when the user wants a repo's AGENTS.md written or updated, root or nested, including "document this for AI coding tools". Writes only verified conventions. Not review-only -> `agentsmd-audit`. Not for CLAUDE.md -> `provider-adapter-author`. | Bash Read Write Edit |
|
Gotchas
- Never invent a command. Every line under a setup/test/build section must come from something you actually found in the repo (
package.jsonscripts, aMakefiletarget, a CI workflow step, a README). If you can't verify a command, don't include it. - Never write to a provider file yourself, in any circumstance:
CLAUDE.md,.cursor/rules/*.mdc,.github/copilot-instructions.mdand their equivalents areprovider-adapter-author's to own. That holds even when the user asks for one in the same breath as AGENTS.md, and even when the file is merely stale or missing a pointer rather than duplicating anything. Detect it and hand off.
Step 1 — Explore the target repo
Before writing anything, gather real facts: package manager and scripts (package.json, pyproject.toml, Cargo.toml, etc.), a Makefile or task runner, CI config (.github/workflows/, etc.) for the commands it actually runs, linter/formatter config files, and any existing docs (README.md, existing AGENTS.md) describing conventions. Note whether any subdirectory looks like its own package with a different stack.
Step 2 — Decide placement
- No
AGENTS.mdat the repo root yet → create one there first, covering whole-repo conventions. - A subdirectory has materially different build/test tooling or conventions than the root → create or update a nested
AGENTS.mdthere, scoped to what's different. Convenience is not a reason to create one — without a distinct stack you are duplicating content the root already covers. Don't repeat root-level content in a nested file: the nearest-file-wins rule means it is read alone, never merged back with the root. - Otherwise → update the existing file(s) in place.
Step 3 — Write or update
AGENTS.md has no required schema. Use only sections that reflect something real about the repo — never fill in every common-sections-checklist heading just because it exists, because a thin accurate file beats a padded generic one. Read references/content-guide.md for section-by-section guidance, a worked example, and what separates useful content from generic padding, before writing.
Step 4 — Check for an existing provider file
Look for CLAUDE.md, .cursor/rules/*.mdc, .github/copilot-instructions.md, or similar in the target repo. If one exists and now duplicates content the AGENTS.md you just wrote/updated already owns, invoke the provider-adapter-author skill on it to reconcile.
Step 5 — Audit and report
Invoke the agentsmd-audit skill directly on the AGENTS.md file(s) you just wrote or updated. This closeout is mandatory, not optional, even when the change looks trivial — never sign the work off on your own judgment. Resolve any FAIL findings before considering the work done — re-invoke this skill's own writing steps to fix them, then re-run the audit, same as any other close-the-loop check. Report what was created/changed, whether a provider file was reconciled, and the audit's final result.