check-skill-refs: catch typos and orphaned catalog entries - #13
Closed
sergiobuilds wants to merge 2 commits into
Closed
check-skill-refs: catch typos and orphaned catalog entries#13sergiobuilds wants to merge 2 commits into
sergiobuilds wants to merge 2 commits into
Conversation
New scripts/check-skill-refs.sh, wired into ci.yml alongside validate-skills.sh. Applies the same drift detection ssotchk looks for — but to the catalog's own cross-skill vocabulary. Two checks: 1. A backticked skill-shaped token that is near a shipped skill name but does not resolve to one is almost certainly a typo. Example — 're0-git-log' when only 're0-git' is shipped. Only near-collisions with an existing shipped name are flagged, so unrelated backticked identifiers pass silently. 2. Every shipped skill must be reachable from README.md, either by a backticked mention or by a link to its SKILL.md path. A skill on disk that README never links to is orphaned; if it should not ship, it belongs elsewhere. Rationale — validate-skills.sh already enforces that plugin.json paths resolve to SKILL.md files. This adds the reverse direction (disk → README) plus a typo guard on incidental references, so a rename that misses README (or misspells the new name in prose) fails CI instead of drifting silently until a reader stumbles on it. Empirically clean on the current catalog: 17 shipped names, 30 scanned files, 0 findings.
…propagate The previous check-1 fed the token loop through a pipe (grep | tr | sort | while read). That put the loop body in a subshell, so `fail=1` set by `err` never reached the final exit-code decision — the script always ended 0 even when it had flagged typos. Switch to `while read ... done < <(...)` so the loop stays in the current shell and `fail` propagates. While here, guard two states that would silently misreport: - empty `shipped` array (no SKILL.md found): fail fast instead of iterating an empty catalog under `set -u`. - missing README.md at repo root: fail fast instead of reporting every skill as orphaned. Verified locally: clean repo exits 0; injecting `re0-git-log` into docs/invocation.md exits 1 with the correct token/file in the message; removing README.md exits 1 with the missing-catalog message; restoring returns to exit 0.
Contributor
Author
|
Cold-read pointed out that check-1 was effectively dead: piping Pushed fix (e976bbd):
Local verification (from a clean checkout of this branch):
Ready for another look. |
Owner
|
Landed in |
LilMGenius
approved these changes
Jul 17, 2026
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
2 participants
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.
New
scripts/check-skill-refs.sh— applies the same drift detectionssotchklooks for, to the catalog's own cross-skill vocabulary.Checks
1. Backticked typo guard
A backticked skill-shaped token that is near a shipped skill name but does not resolve to one is almost certainly a typo — for example,
re0-git-logwhen onlyre0-gitis shipped. Only near-collisions with an existing shipped name are flagged; unrelated backticked identifiers pass silently.2. Orphan guard
Every shipped skill must be reachable from
README.md, either by a backticked mention or by a link to itsSKILL.mdpath. A skill on disk that README never links to is orphaned.Complements validate-skills.sh
validate-skills.shalready enforces thatplugin.jsonpaths resolve toSKILL.mdfiles. This adds the reverse direction (disk → README) plus a typo guard on incidental references, so a rename that misses README (or misspells the new name in prose) fails CI instead of drifting silently.Verification
Empirically clean on the current catalog.
CI wiring — one line
The script is not yet wired into CI in this PR (OAuth workflow scope). Suggested addition after
Validate the skill catalogstep in.github/workflows/ci.yml:Happy to land the wiring in a follow-up, or fold into this PR if preferred.