docs: trim skill READMEs and ADR/changelog narration
Two related simplification-audit findings, bundled because they edit some of the same skill-audit files and splitting would fragment single-file diffs. Finding 10: delete 48 per-skill/reference README.md files (they restated SKILL.md in narrative form and no agent ever loads them) plus 2 scaffold templates. Drop the README criterion from skill-audit's file-structure.md and finding-criteria.md, and the README-generation step from skill-author's new-skill.sh; update new-skill.bats to match. Plugin-root READMEs are kept intentionally, out of scope. Finding 12: strip historical ADR-0020/ADR-0023 citations and changelog-style narration from model-facing skill content across kyberforge and git plugin skills. Delete skill-author's one-time retrofit.md migration guide and its references. Some ADR-0023 tags were not narration but check-rtk-prefix's required opt-out marker for intentionally-bare git commands -- those were restored, not stripped. Mirror re-synced and full pre-commit/pre-push suite verified green. Refs: SIMPLIFICATION-AUDIT.md findings 10, 12 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
This commit is contained in:
@@ -1,38 +0,0 @@
|
||||
# agentsmd-audit
|
||||
|
||||
Audit a target repo's AGENTS.md file(s) for embedded secrets, structural completeness, and drift.
|
||||
|
||||
## What it does
|
||||
|
||||
Runs a single combined pass across every AGENTS.md file in a repo (root and any nested monorepo files): flags embedded secrets/credentials, checks structure against the agents.md common-sections checklist, and resolves referenced commands/paths against the actual repo to catch stale documentation. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix. Never inspects provider-specific adapter files (CLAUDE.md, etc.) and never writes or fixes anything.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/agentsmd-audit
|
||||
```
|
||||
|
||||
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 |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `scripts/validate-secrets.sh` | Scans AGENTS.md files for embedded secrets, API keys, tokens, connection strings |
|
||||
| `scripts/validate-structure.sh` | Checks for empty/placeholder content, common-sections checklist, nested-vs-root duplication |
|
||||
| `scripts/validate-drift.sh` | Resolves referenced npm/make commands and file paths against the repo |
|
||||
| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to |
|
||||
| `scripts/README.md` | Directory documentation for `scripts/` |
|
||||
| `tests/README.md` | (source-only) Bats test dependency and run instructions |
|
||||
| `tests/validate-secrets.bats` | (source-only) Bats test suite for `scripts/validate-secrets.sh` |
|
||||
| `tests/validate-structure.bats` | (source-only) Bats test suite for `scripts/validate-structure.sh` |
|
||||
| `tests/validate-drift.bats` | (source-only) Bats test suite for `scripts/validate-drift.sh` |
|
||||
|
||||
Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agentsmd-audit/`) but are
|
||||
not present in an installed plugin: the repo's `scripts/sync-plugin-content.sh` strips
|
||||
`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
|
||||
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.
|
||||
@@ -1,27 +0,0 @@
|
||||
# agentsmd-author
|
||||
|
||||
Create or update a target repo's AGENTS.md file(s) by exploring the repo for real conventions.
|
||||
|
||||
## What it does
|
||||
|
||||
Explores a target repo (package manager scripts, Makefile/task runner, CI config, linter config, existing docs) and writes or updates `AGENTS.md` with only verified commands and conventions — never invented ones. Supports nested monorepo placement, following the agents.md standard's nearest-file-wins precedence. Closes every run by invoking `agentsmd-audit` inline, and hands off to `provider-adapter-author` when an existing provider-specific file (CLAUDE.md, etc.) now duplicates content AGENTS.md owns.
|
||||
|
||||
## Before you start
|
||||
|
||||
The `agentsmd-audit` skill must be available (co-installed in the `core` plugin) — this skill invokes it as a mandatory closeout step.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/agentsmd-author
|
||||
```
|
||||
|
||||
Provide the target repo root (defaults to the current directory) and, if relevant, which subdirectory should get a nested AGENTS.md.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `references/content-guide.md` | Section-by-section AGENTS.md content guidance, a worked example, and monorepo/nested-file precedence rules |
|
||||
| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to |
|
||||
@@ -1,36 +0,0 @@
|
||||
# provider-adapter-author
|
||||
|
||||
Convert a target repo's provider-specific instruction file (CLAUDE.md, .cursor/rules, copilot-instructions.md, etc.) into a thin adapter over AGENTS.md.
|
||||
|
||||
## What it does
|
||||
|
||||
Detects a provider-specific AI instruction file in a target repo, diffs it against the repo's `AGENTS.md`, and rewrites it down to a minimal reference — an `@AGENTS.md`-style import for providers that support one, or a text pointer for those that don't — plus only genuinely provider-specific additions. Self-validates its own output with a bundled deterministic script (no LLM judgment, no separate audit skill) before finishing.
|
||||
|
||||
## Before you start
|
||||
|
||||
The target repo must already have an `AGENTS.md`. If it doesn't, run `agentsmd-author` first — this skill never creates or edits `AGENTS.md` itself.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/provider-adapter-author
|
||||
```
|
||||
|
||||
Provide the path to the provider-specific file to convert (and the target repo root, if not inferable). Can be invoked directly, or composed into by `agentsmd-author` when it detects an existing provider file with content overlapping AGENTS.md.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `references/provider-matrix.md` | Loaded at Step 1 before searching, unless the target is already a known root `CLAUDE.md`: known files per provider, which ones resolve a cross-file import, the validator flag each needs, and the rule that a standalone run and a run composed into by `agentsmd-author` behave identically |
|
||||
| `references/sources.md` | Provenance record — the in-repo ADR precedent this skill's design is modeled on |
|
||||
| `scripts/validate-adapter.sh` | Self-check gate: reference to AGENTS.md present, no excessive duplication, adapter stays thin |
|
||||
| `scripts/README.md` | Directory documentation for `scripts/` |
|
||||
| `tests/README.md` | (source-only) Bats test dependency and run instructions |
|
||||
| `tests/validate-adapter.bats` | (source-only) Bats test suite for `scripts/validate-adapter.sh` |
|
||||
|
||||
Rows marked **(source-only)** exist in the authoring source (`.apm/skills/provider-adapter-author/`)
|
||||
but are not present in an installed plugin: the repo's `scripts/sync-plugin-content.sh` strips
|
||||
`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
|
||||
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.
|
||||
@@ -1,38 +0,0 @@
|
||||
# agentsmd-audit
|
||||
|
||||
Audit a target repo's AGENTS.md file(s) for embedded secrets, structural completeness, and drift.
|
||||
|
||||
## What it does
|
||||
|
||||
Runs a single combined pass across every AGENTS.md file in a repo (root and any nested monorepo files): flags embedded secrets/credentials, checks structure against the agents.md common-sections checklist, and resolves referenced commands/paths against the actual repo to catch stale documentation. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix. Never inspects provider-specific adapter files (CLAUDE.md, etc.) and never writes or fixes anything.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/agentsmd-audit
|
||||
```
|
||||
|
||||
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 |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `scripts/validate-secrets.sh` | Scans AGENTS.md files for embedded secrets, API keys, tokens, connection strings |
|
||||
| `scripts/validate-structure.sh` | Checks for empty/placeholder content, common-sections checklist, nested-vs-root duplication |
|
||||
| `scripts/validate-drift.sh` | Resolves referenced npm/make commands and file paths against the repo |
|
||||
| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to |
|
||||
| `scripts/README.md` | Directory documentation for `scripts/` |
|
||||
| `tests/README.md` | (source-only) Bats test dependency and run instructions |
|
||||
| `tests/validate-secrets.bats` | (source-only) Bats test suite for `scripts/validate-secrets.sh` |
|
||||
| `tests/validate-structure.bats` | (source-only) Bats test suite for `scripts/validate-structure.sh` |
|
||||
| `tests/validate-drift.bats` | (source-only) Bats test suite for `scripts/validate-drift.sh` |
|
||||
|
||||
Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agentsmd-audit/`) but are
|
||||
not present in an installed plugin: the repo's `scripts/sync-plugin-content.sh` strips
|
||||
`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
|
||||
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.
|
||||
@@ -1,27 +0,0 @@
|
||||
# agentsmd-author
|
||||
|
||||
Create or update a target repo's AGENTS.md file(s) by exploring the repo for real conventions.
|
||||
|
||||
## What it does
|
||||
|
||||
Explores a target repo (package manager scripts, Makefile/task runner, CI config, linter config, existing docs) and writes or updates `AGENTS.md` with only verified commands and conventions — never invented ones. Supports nested monorepo placement, following the agents.md standard's nearest-file-wins precedence. Closes every run by invoking `agentsmd-audit` inline, and hands off to `provider-adapter-author` when an existing provider-specific file (CLAUDE.md, etc.) now duplicates content AGENTS.md owns.
|
||||
|
||||
## Before you start
|
||||
|
||||
The `agentsmd-audit` skill must be available (co-installed in the `core` plugin) — this skill invokes it as a mandatory closeout step.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/agentsmd-author
|
||||
```
|
||||
|
||||
Provide the target repo root (defaults to the current directory) and, if relevant, which subdirectory should get a nested AGENTS.md.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `references/content-guide.md` | Section-by-section AGENTS.md content guidance, a worked example, and monorepo/nested-file precedence rules |
|
||||
| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to |
|
||||
@@ -1,36 +0,0 @@
|
||||
# provider-adapter-author
|
||||
|
||||
Convert a target repo's provider-specific instruction file (CLAUDE.md, .cursor/rules, copilot-instructions.md, etc.) into a thin adapter over AGENTS.md.
|
||||
|
||||
## What it does
|
||||
|
||||
Detects a provider-specific AI instruction file in a target repo, diffs it against the repo's `AGENTS.md`, and rewrites it down to a minimal reference — an `@AGENTS.md`-style import for providers that support one, or a text pointer for those that don't — plus only genuinely provider-specific additions. Self-validates its own output with a bundled deterministic script (no LLM judgment, no separate audit skill) before finishing.
|
||||
|
||||
## Before you start
|
||||
|
||||
The target repo must already have an `AGENTS.md`. If it doesn't, run `agentsmd-author` first — this skill never creates or edits `AGENTS.md` itself.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/provider-adapter-author
|
||||
```
|
||||
|
||||
Provide the path to the provider-specific file to convert (and the target repo root, if not inferable). Can be invoked directly, or composed into by `agentsmd-author` when it detects an existing provider file with content overlapping AGENTS.md.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SKILL.md` | Skill instructions for agents |
|
||||
| `references/provider-matrix.md` | Loaded at Step 1 before searching, unless the target is already a known root `CLAUDE.md`: known files per provider, which ones resolve a cross-file import, the validator flag each needs, and the rule that a standalone run and a run composed into by `agentsmd-author` behave identically |
|
||||
| `references/sources.md` | Provenance record — the in-repo ADR precedent this skill's design is modeled on |
|
||||
| `scripts/validate-adapter.sh` | Self-check gate: reference to AGENTS.md present, no excessive duplication, adapter stays thin |
|
||||
| `scripts/README.md` | Directory documentation for `scripts/` |
|
||||
| `tests/README.md` | (source-only) Bats test dependency and run instructions |
|
||||
| `tests/validate-adapter.bats` | (source-only) Bats test suite for `scripts/validate-adapter.sh` |
|
||||
|
||||
Rows marked **(source-only)** exist in the authoring source (`.apm/skills/provider-adapter-author/`)
|
||||
but are not present in an installed plugin: the repo's `scripts/sync-plugin-content.sh` strips
|
||||
`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
|
||||
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.
|
||||
Reference in New Issue
Block a user