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,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.
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user