diff --git a/plugins/core/.apm/skills/agentsmd-author/SKILL.md b/plugins/core/.apm/skills/agentsmd-author/SKILL.md index a38604d..6dc9d1f 100644 --- a/plugins/core/.apm/skills/agentsmd-author/SKILL.md +++ b/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. diff --git a/plugins/core/skills/agentsmd-author/SKILL.md b/plugins/core/skills/agentsmd-author/SKILL.md index a38604d..6dc9d1f 100644 --- a/plugins/core/skills/agentsmd-author/SKILL.md +++ b/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.