refactor(skills): retrofit the corpus to the ADR-0020 context contract #129
@@ -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 |
|
||||
|
||||
@@ -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 <repo-root>
|
||||
bash scripts/validate-drift.sh <repo-root>
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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 <repo-root>
|
||||
bash scripts/validate-drift.sh <repo-root>
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user