Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

refactor(skills): retrofit the corpus to the ADR-0020 context contract #129

Merged
Defame1297 merged 89 commits from refactor/adr0020-skill-retrofit into main 2026-09-01 13:47:47 +00:00
Conversation 2 Commits 89 Files Changed 420 +22 -36
4 changed files with 22 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit f0526b310d - Show all commits

3
plugins/core/.apm/skills/agentsmd-audit/README.md
View File

@@ -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. 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 ## Files
| File | Purpose | | File | Purpose |

26
plugins/core/.apm/skills/agentsmd-audit/SKILL.md
View File

@@ -1,20 +1,11 @@
--- ---
name: agentsmd-audit name: agentsmd-audit
description: > description: >
Use when the user wants to review a repo's AGENTS.md file, says "audit this Use when the user wants a repo's AGENTS.md audited — "audit this AGENTS.md",
AGENTS.md", "check my AGENTS.md", "is this AGENTS.md any good", or wants to "is this AGENTS.md safe to commit" — or after a hand-edit outside
know if AGENTS.md is safe to commit — even if they don't use the word `agentsmd-author`. Reports secrets, structure and drift; never edits.
"audit". Also invoke proactively after agentsmd-author creates or updates Not for CLAUDE.md or provider files -> `provider-adapter-author`.
AGENTS.md, or after a hand-edit made outside agentsmd-author. Audits a Not writing AGENTS.md -> `agentsmd-author`.
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.
allowed-tools: Bash Read allowed-tools: Bash Read
metadata: metadata:
category: docs category: docs
@@ -23,14 +14,13 @@ metadata:
- context7-websites-agents-md - context7-websites-agents-md
- context7-agentsmd-agents-md - context7-agentsmd-agents-md
- governance-secrets-hard-prohibition - governance-secrets-hard-prohibition
version: "0.1.1" version: "0.1.2"
--- ---
## Gotchas ## 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. - 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. - Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope.
- 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.
- Gather findings internally; don't narrate PASS/FAIL per check as you go — surface them only in the final report. - 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 ## Step 1 — Run the validators
@@ -41,7 +31,7 @@ bash scripts/validate-structure.sh <repo-root>
bash scripts/validate-drift.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 ## Step 2 — Report

3
plugins/core/skills/agentsmd-audit/README.md
View File

@@ -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. 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 ## Files
| File | Purpose | | File | Purpose |

26
plugins/core/skills/agentsmd-audit/SKILL.md
View File

@@ -1,20 +1,11 @@
--- ---
name: agentsmd-audit name: agentsmd-audit
description: > description: >
Use when the user wants to review a repo's AGENTS.md file, says "audit this Use when the user wants a repo's AGENTS.md audited — "audit this AGENTS.md",
AGENTS.md", "check my AGENTS.md", "is this AGENTS.md any good", or wants to "is this AGENTS.md safe to commit" — or after a hand-edit outside
know if AGENTS.md is safe to commit — even if they don't use the word `agentsmd-author`. Reports secrets, structure and drift; never edits.
"audit". Also invoke proactively after agentsmd-author creates or updates Not for CLAUDE.md or provider files -> `provider-adapter-author`.
AGENTS.md, or after a hand-edit made outside agentsmd-author. Audits a Not writing AGENTS.md -> `agentsmd-author`.
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.
allowed-tools: Bash Read allowed-tools: Bash Read
metadata: metadata:
category: docs category: docs
@@ -23,14 +14,13 @@ metadata:
- context7-websites-agents-md - context7-websites-agents-md
- context7-agentsmd-agents-md - context7-agentsmd-agents-md
- governance-secrets-hard-prohibition - governance-secrets-hard-prohibition
version: "0.1.1" version: "0.1.2"
--- ---
## Gotchas ## 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. - 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. - Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope.
- 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.
- Gather findings internally; don't narrate PASS/FAIL per check as you go — surface them only in the final report. - 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 ## Step 1 — Run the validators
@@ -41,7 +31,7 @@ bash scripts/validate-structure.sh <repo-root>
bash scripts/validate-drift.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 ## Step 2 — Report