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:
2026-09-12 18:38:09 +00:00
parent 9eb8bc7e48
commit edcc57c0d6
167 changed files with 132 additions and 3897 deletions

View File

@@ -1,55 +0,0 @@
---
source_keys: []
---
# references/
## create.md
The create flow, loaded from SKILL.md Step 1 when no agent file exists at the target path.
Covers: prerequisites, the scaffold script and its scope walk-up, what to fill in at every scope,
and populating or deleting the package-root `sources.md`.
## improve.md
The improve flow, loaded from SKILL.md Step 1 when a file exists and at least one improvement
signal is present. Covers: signal verification, partial-pair recovery, root-cause grouping,
generalizing rather than patching, delegation over growth, and the ADR-0020 retrofit rule.
## contract.md
The description and body contract, loaded from SKILL.md Step 3 before any description is written
or any body restructured. Covers: the three-part description shape, banned description content,
boundary-target resolution, the 250/400 length tiers, the body role-instruction pattern, the
delegation rule that replaces a body word gate, and the invocation axis.
## plugin-scope.md
Field rules and the pre-audit checklist for the single vendor-neutral `.apm/agents/<name>.agent.md`
file. Loaded from SKILL.md Step 2 when the scaffold resolves plugin/APM scope.
## project-user-scope.md
Field rules and the pre-audit checklist for the Claude Code `.md` + Copilot `.agent.md` pair,
including the two distinct Copilot formats. Loaded from SKILL.md Step 2 when the scaffold resolves
project or user scope.
## deployment-modes.md
Scope hierarchy and precedence, scoped identifiers for plugin subdirectory agents, cache isolation
behaviour, and Copilot CLI path conventions. Loaded from SKILL.md Step 2 when precedence, paths or
cache isolation matter to the run.
## scripts.md
Conventions for the `new-agent.sh` scaffold script, the templates it copies, and any future script
in this skill. Loaded from `create.md` Step 1 when the script or a template has to change. Covers:
the no-interactive-prompts rule, structured output, idempotency, template variables, file
placement, error messages, and the no-restated-field-roster rule that `tests/new-agent.bats`
enforces.
## sources.md
Research provenance record for this skill. Lists the upstream research sources
(claude-code-plugins and github-copilot-plugins research docs) that informed SKILL.md and the
reference files. Used by `skill-audit` to validate the provenance chain.

View File

@@ -6,7 +6,7 @@ source_keys:
# The agent description and body contract
House contract, set by ADR-0020. The counts and the boundary targets are enforced by
House contract. The counts and the boundary targets are enforced by
`agent-audit`'s `scripts/validate.sh`; the prose patterns by the Vale styles it bundles; the
judgment calls by its reference files.
@@ -40,9 +40,8 @@ Banned from a description; move it to the body or to `README.md`:
- Restating the same trigger twice in two registers — a verb list, then the same verbs re-quoted
as user phrasings. This is a FAIL, not a suggestion.
**Do not open with an action verb.** "Reviews…", "Analyzes…", "Generates…" was the old house rule
and ADR-0020 deleted it: the opener is `Use when`, matching every skill in this corpus, so one
router reads one shape.
**Do not open with an action verb.** The opener is `Use when`, matching every skill in this corpus,
so one router reads one shape.
**"Use proactively" is Claude Code-only, and conditional even there.** The phrase steers the
Claude Code runtime to offer an agent unprompted and does nothing anywhere else, so where it may

View File

@@ -66,9 +66,10 @@ answer is no.
all caps (ALWAYS/NEVER) is usually better reframed as why the behaviour matters, so the agent can
apply judgment at the edges.
**Retrofit before extending.** Any agent predating ADR-0020 has to meet the description contract
before any other edit lands — the gates are hot and carry no baseline file, so a one-line fix to a
non-compliant agent cannot be committed until its description meets `references/contract.md`.
**Retrofit before extending.** Any agent whose description does not meet the contract has to be
brought into compliance before any other edit lands — the gates are hot and carry no baseline file,
so a one-line fix to a non-compliant agent cannot be committed until its description meets
`references/contract.md`.
Treat that retrofit as part of the same change, not a follow-up.
**Re-check the scope rules.** Read the reference for the resolved scope (`SKILL.md` Step 2) and