holocron/plugins/core/skills/agentsmd-author/SKILL.md

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	category source_keys version docs agents-md-official context7-websites-agents-md context7-agentsmd-agents-md 0.1.2

Gotchas

• Never invent a command. Every line under a setup/test/build section must come from something you actually found in the repo (package.json scripts, a Makefile target, 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.md and their equivalents are provider-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.md at 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.md there, 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.