Defame1297
1c3af75642
Both branches of the flag reduced to the same expression, so the option was inert: a caller who asked for the no-import form got the import-form check anyway and a passing result that meant nothing. Two further defects in the same validator: --max-lines failed silently when given a value it could not use, and the Fix text told the agent to edit AGENTS.md when the offending content is the provider adapter's. The boundary clauses now name the operation being routed rather than the file type, which was ambiguous where both skills touch the same file. Addresses #115.
3.6 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 converting 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, invoke the provider-adapter-author skill on it to reconcile — whether it duplicates content the AGENTS.md you just wrote/updated now owns, or is merely stale or missing a pointer to it. Never edit it yourself in either case.
Step 5 — Audit and report
Invoke the agentsmd-audit skill on the target repo root — its validators take a <repo-root> and walk the tree for every AGENTS.md themselves; there is no per-file entry point. 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.