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

@@ -1,20 +1,10 @@
 ---
 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.
+  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`.
 allowed-tools: Bash Read Write Edit
 metadata:
   category: docs
@@ -22,16 +12,13 @@ metadata:
     - agents-md-official
     - context7-websites-agents-md
     - context7-agentsmd-agents-md
-  version: "0.1.1"
+  version: "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.
-- 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.
+- 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
 
@@ -40,17 +27,17 @@ Before writing anything, gather real facts: package manager and scripts (`packag
 ## 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.
+- 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
 
-Use only sections that reflect something real about the repo — never fill in every common-sections-checklist heading just because it exists. Read `references/content-guide.md` for section-by-section guidance, a worked example, and what separates useful content from generic padding, before writing.
+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 — don't rewrite it yourself.
+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. 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.
+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.

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

@@ -1,20 +1,10 @@
 ---
 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.
+  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`.
 allowed-tools: Bash Read Write Edit
 metadata:
   category: docs
@@ -22,16 +12,13 @@ metadata:
     - agents-md-official
     - context7-websites-agents-md
     - context7-agentsmd-agents-md
-  version: "0.1.1"
+  version: "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.
-- 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.
+- 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
 
@@ -40,17 +27,17 @@ Before writing anything, gather real facts: package manager and scripts (`packag
 ## 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.
+- 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
 
-Use only sections that reflect something real about the repo — never fill in every common-sections-checklist heading just because it exists. Read `references/content-guide.md` for section-by-section guidance, a worked example, and what separates useful content from generic padding, before writing.
+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 — don't rewrite it yourself.
+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. 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.
+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.