---
name: agentsmd-author
description: >
  Use when the user wants to create or update a repo's AGENTS.md file
  ("write an AGENTS.md for this repo", "add setup/test instructions for
  agents", "update AGENTS.md", "give this package its own AGENTS.md") — even
  if they don't name the file explicitly, e.g. "document this for AI coding
  tools" or "make sure agents know how to run tests here". Writes/updates
  AGENTS.md by exploring the target repo for real build, test, lint, and
  style conventions — never invents commands. Supports nested monorepo
  placement (a subdirectory can get its own AGENTS.md following
  nearest-file-wins precedence). Closes every run by invoking agentsmd-audit
  inline, and calls provider-adapter-author when an existing provider file
  (CLAUDE.md, etc.) now duplicates what AGENTS.md owns. Do not use to review
  an existing AGENTS.md without changing it — use agentsmd-audit instead. Do
  not use to convert CLAUDE.md/.cursor/rules into a thin adapter — use
  provider-adapter-author instead.
allowed-tools: Bash Read Write Edit
metadata:
  category: docs
  source_keys:
    - agents-md-official
    - context7-websites-agents-md
    - context7-agentsmd-agents-md
  version: "0.1.0"
---

## 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.
- AGENTS.md has no required schema — don't force every common-sections-checklist heading into every repo. Include only sections that reflect something real about this repo; a thin, accurate file beats a padded, generic one.
- Nested placement is for genuinely different conventions, not convenience. Only create a subdirectory AGENTS.md when that subtree has its own build tool, stack, or conventions distinct from the root — otherwise you're duplicating content the root already covers, which the nearest-file-wins rule doesn't merge back together.
- This skill never touches CLAUDE.md, `.cursor/rules/*.mdc`, `copilot-instructions.md`, or similar provider files directly — that's `provider-adapter-author`'s job. Detect and hand off; don't reconcile it yourself.
- This skill never audits on its own judgment — the closing `agentsmd-audit` invocation is mandatory, not optional, even when the change looks trivial.

## 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. Don't repeat root-level content — the nearest-file-wins rule means the nested file is read alone, not merged with the root.
- Otherwise → update the existing file(s) in place.

## Step 3 — Write or update

Use only sections that reflect something real about the repo. Common sections from the agents.md standard — setup/build commands, code style, testing instructions, security considerations, commit/PR conventions — are a checklist to consider, not a template to fill blindly. Prefer concrete commands and file paths over general advice.

## 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 — don't rewrite it yourself.

## Step 5 — Audit and report

Invoke the `agentsmd-audit` skill directly on the AGENTS.md file(s) you just wrote or updated. 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.