diff --git a/plugins/core/.apm/skills/agentsmd-audit/README.md b/plugins/core/.apm/skills/agentsmd-audit/README.md index d863d94..658df6f 100644 --- a/plugins/core/.apm/skills/agentsmd-audit/README.md +++ b/plugins/core/.apm/skills/agentsmd-audit/README.md @@ -14,6 +14,9 @@ Runs a single combined pass across every AGENTS.md file in a repo (root and any Provide the path to the repo root to audit when invoking. +Also invoke it proactively after `agentsmd-author` creates or updates an AGENTS.md, or after a +hand-edit made outside `agentsmd-author` — the audit is what confirms the result is safe to commit. + ## Files | File | Purpose | diff --git a/plugins/core/.apm/skills/agentsmd-audit/SKILL.md b/plugins/core/.apm/skills/agentsmd-audit/SKILL.md index d8a4a34..8d578d4 100644 --- a/plugins/core/.apm/skills/agentsmd-audit/SKILL.md +++ b/plugins/core/.apm/skills/agentsmd-audit/SKILL.md @@ -1,20 +1,11 @@ --- name: agentsmd-audit description: > - Use when the user wants to review a repo's AGENTS.md file, says "audit this - AGENTS.md", "check my AGENTS.md", "is this AGENTS.md any good", or wants to - know if AGENTS.md is safe to commit — even if they don't use the word - "audit". Also invoke proactively after agentsmd-author creates or updates - AGENTS.md, or after a hand-edit made outside agentsmd-author. Audits a - target repo's AGENTS.md file(s) — root and any nested monorepo files — for - embedded secrets/credentials, structural completeness against the - agents.md common-sections checklist, and drift (referenced commands or - paths that no longer resolve against the repo). Produces a compact - findings report (findings only, no PASS noise) with Why and Fix per - finding. Do not use to audit CLAUDE.md, .cursor/rules, or other - provider-specific adapter files — that's provider-adapter-author's - self-contained concern. Do not use to fix or write AGENTS.md content — use - agentsmd-author instead. + Use when the user wants a repo's AGENTS.md audited — "audit this AGENTS.md", + "is this AGENTS.md safe to commit" — or after a hand-edit outside + `agentsmd-author`. Reports secrets, structure and drift; never edits. + Not for CLAUDE.md or provider files -> `provider-adapter-author`. + Not writing AGENTS.md -> `agentsmd-author`. allowed-tools: Bash Read metadata: category: docs @@ -23,14 +14,13 @@ metadata: - context7-websites-agents-md - context7-agentsmd-agents-md - governance-secrets-hard-prohibition - version: "0.1.1" + version: "0.1.2" --- ## Gotchas - Always run all three checks — this skill does a single combined pass, not staged/gated passes. Don't skip structure or drift checks just because a secrets FAIL was found. -- Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope. If one exists and duplicates AGENTS.md content, that's `provider-adapter-author`'s concern, not this skill's. -- A missing common section (e.g. no "Security" heading) is informational, not a failure — not every repo needs every section from the checklist. Only flag a FAIL when the file is empty, entirely unfilled placeholder text, or contains a real embedded secret/stale reference. +- Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope. - Gather findings internally; don't narrate PASS/FAIL per check as you go — surface them only in the final report. ## Step 1 — Run the validators @@ -41,7 +31,7 @@ bash scripts/validate-structure.sh bash scripts/validate-drift.sh ``` -Each script walks the repo for every `AGENTS.md` file (root and nested, excluding `.git`, `node_modules`, `vendor`, and similar) and prints `FAIL`/`INFO`/`SUGGESTION` lines with `Why`/`Fix` (or `Note`) per finding. A nonzero exit means at least one FAIL was found in that dimension. If a script cannot execute (`python3` unavailable, Bash denied), fall back to manual review: scan for real-looking credentials, check common sections are present, and spot-check a few referenced commands/paths by hand. +Each script walks the repo for every `AGENTS.md` file (root and nested, excluding `.git`, `node_modules`, `vendor`, and similar) and prints `FAIL`/`INFO`/`SUGGESTION` lines with `Why`/`Fix` (or `Note`) per finding. A nonzero exit means at least one FAIL was found in that dimension. If a script cannot execute (`python3` unavailable, Bash denied), fall back to manual review: scan for real-looking credentials, check common sections are present, and spot-check a few referenced commands/paths by hand. Grade a manual finding the way the scripts grade theirs: a missing common section (e.g. no "Security" heading) is informational, not a failure — not every repo needs every section from the checklist. Only flag a FAIL when the file is empty, entirely unfilled placeholder text, or contains a real embedded secret/stale reference. ## Step 2 — Report diff --git a/plugins/core/skills/agentsmd-audit/README.md b/plugins/core/skills/agentsmd-audit/README.md index d863d94..658df6f 100644 --- a/plugins/core/skills/agentsmd-audit/README.md +++ b/plugins/core/skills/agentsmd-audit/README.md @@ -14,6 +14,9 @@ Runs a single combined pass across every AGENTS.md file in a repo (root and any Provide the path to the repo root to audit when invoking. +Also invoke it proactively after `agentsmd-author` creates or updates an AGENTS.md, or after a +hand-edit made outside `agentsmd-author` — the audit is what confirms the result is safe to commit. + ## Files | File | Purpose | diff --git a/plugins/core/skills/agentsmd-audit/SKILL.md b/plugins/core/skills/agentsmd-audit/SKILL.md index d8a4a34..8d578d4 100644 --- a/plugins/core/skills/agentsmd-audit/SKILL.md +++ b/plugins/core/skills/agentsmd-audit/SKILL.md @@ -1,20 +1,11 @@ --- name: agentsmd-audit description: > - Use when the user wants to review a repo's AGENTS.md file, says "audit this - AGENTS.md", "check my AGENTS.md", "is this AGENTS.md any good", or wants to - know if AGENTS.md is safe to commit — even if they don't use the word - "audit". Also invoke proactively after agentsmd-author creates or updates - AGENTS.md, or after a hand-edit made outside agentsmd-author. Audits a - target repo's AGENTS.md file(s) — root and any nested monorepo files — for - embedded secrets/credentials, structural completeness against the - agents.md common-sections checklist, and drift (referenced commands or - paths that no longer resolve against the repo). Produces a compact - findings report (findings only, no PASS noise) with Why and Fix per - finding. Do not use to audit CLAUDE.md, .cursor/rules, or other - provider-specific adapter files — that's provider-adapter-author's - self-contained concern. Do not use to fix or write AGENTS.md content — use - agentsmd-author instead. + Use when the user wants a repo's AGENTS.md audited — "audit this AGENTS.md", + "is this AGENTS.md safe to commit" — or after a hand-edit outside + `agentsmd-author`. Reports secrets, structure and drift; never edits. + Not for CLAUDE.md or provider files -> `provider-adapter-author`. + Not writing AGENTS.md -> `agentsmd-author`. allowed-tools: Bash Read metadata: category: docs @@ -23,14 +14,13 @@ metadata: - context7-websites-agents-md - context7-agentsmd-agents-md - governance-secrets-hard-prohibition - version: "0.1.1" + version: "0.1.2" --- ## Gotchas - Always run all three checks — this skill does a single combined pass, not staged/gated passes. Don't skip structure or drift checks just because a secrets FAIL was found. -- Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope. If one exists and duplicates AGENTS.md content, that's `provider-adapter-author`'s concern, not this skill's. -- A missing common section (e.g. no "Security" heading) is informational, not a failure — not every repo needs every section from the checklist. Only flag a FAIL when the file is empty, entirely unfilled placeholder text, or contains a real embedded secret/stale reference. +- Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope. - Gather findings internally; don't narrate PASS/FAIL per check as you go — surface them only in the final report. ## Step 1 — Run the validators @@ -41,7 +31,7 @@ bash scripts/validate-structure.sh bash scripts/validate-drift.sh ``` -Each script walks the repo for every `AGENTS.md` file (root and nested, excluding `.git`, `node_modules`, `vendor`, and similar) and prints `FAIL`/`INFO`/`SUGGESTION` lines with `Why`/`Fix` (or `Note`) per finding. A nonzero exit means at least one FAIL was found in that dimension. If a script cannot execute (`python3` unavailable, Bash denied), fall back to manual review: scan for real-looking credentials, check common sections are present, and spot-check a few referenced commands/paths by hand. +Each script walks the repo for every `AGENTS.md` file (root and nested, excluding `.git`, `node_modules`, `vendor`, and similar) and prints `FAIL`/`INFO`/`SUGGESTION` lines with `Why`/`Fix` (or `Note`) per finding. A nonzero exit means at least one FAIL was found in that dimension. If a script cannot execute (`python3` unavailable, Bash denied), fall back to manual review: scan for real-looking credentials, check common sections are present, and spot-check a few referenced commands/paths by hand. Grade a manual finding the way the scripts grade theirs: a missing common section (e.g. no "Security" heading) is informational, not a failure — not every repo needs every section from the checklist. Only flag a FAIL when the file is empty, entirely unfilled placeholder text, or contains a real embedded secret/stale reference. ## Step 2 — Report