feat: gate skill directories on README feature-list coverage - #257
Merged
Conversation
scripts/check-skill-shape.sh gains rule 7: every skills/<name>/ directory must appear as a backtick-wrapped token in README.md, mirroring rule 6's existing docs/cheatsheet.md check. A scan that cannot run faults (exit 2) rather than reporting a false absence, per the fault/report contract ADR 0025 states as the live head of the 0005 -> 0024 -> 0025 chain. scripts/check-skill-shape-test.sh gains fixture coverage for a skill missing from README, one documented via prose only (proving membership, not table position), and rule 7's own require_readable guard on a scan-cannot-run fault. Closes #238 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ck-238 # Conflicts: # .claude-plugin/plugin.json
…ck-238 # Conflicts: # .claude-plugin/plugin.json
…ck-238 # Conflicts: # .claude-plugin/plugin.json
…ck-238 # Conflicts: # .claude-plugin/plugin.json
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #238
scripts/check-skill-shape.shalready had Rule 6, which asserts that everyskills/<name>/directory is named indocs/cheatsheet.mdas abacktick-wrapped token. Nothing did the same for the README's feature list, so
a skill could be added, documented in the cheat sheet, and never reach the
README with no gate noticing.
What this adds
Rule 7: the same set-membership check, pointed at
README.md.It is deliberately the narrowest possible reading of the documents. For each
skill directory it asks one question — does that name appear in
README.mdas abacktick-wrapped token — and nothing about wording, table shape, ordering or
grouping. Anatomy rule 4 forbids a gate that asserts on prose; a structural
check that resolves a directory name against a document is explicitly welcome,
and Rule 6 is the standing precedent this mirrors.
Error contract
Governed by
docs/adr/0025-a-skip-reports-the-condition-not-the-cause.md(Accepted 2026-08-19), the live head of the
0005 → 0024 → 0025chain.rgscan exits> 1→fault, exit 2, naming the rule.rgscan exits1(genuine absence) →report, exit 1, naming the skill andREADME.md.A scan that could not run is never collapsed into "not found".
The gate passes on merge, and that is expected
All 28 current skill directories already appear in
README.md, so Rule 7 goesgreen immediately. That is not evidence the rule is inert — the defect it fixes
is that nothing would catch a future omission.
The distinction matters for the tests, so they do not inherit the same
blindness.
scripts/check-skill-shape-test.shbuilds syntheticskill/README/cheatsheet trees to exercise the absent case directly, which is the
technique Rule 6's existing tests already use. New Case 27 covers the fault path
by shimming
rgto remove the scratch list between Rule 6's scan and Rule 7'sre-open — the same shape as the existing Case 22, one loop later.
The tests were made to fail before they passed. The implementation was
stashed, the new cases run against the pre-Rule-7 script and observed to redden,
then the implementation restored and the cases observed to go green. One
intermediate false redden surfaced during that check — the first fixture tripped
Rule 6 rather than Rule 7 — and was corrected inside the fixture tree so only the
README gap is under test.
Non-user-facing skills
No exemption mechanism is included. No deliberately undocumented skill exists in
this repository today, and building configuration for a case that does not exist
is the speculative surface the repository's own instructions rule out. If such a
skill is ever added, the rule will report it and that report is the moment to
decide, with a real example in hand.
Verification
just verifyrun bare, exit 0, andjust shape-checkgreen standalone againstthe real 28-skill tree. The managed pre-push hook re-ran the whole suite in its
isolated worktree on push, green.
The base-branch workflow runs this merge would trigger are not covered by that
evidence.