fix(skill-lint): check that every skill package is registered - #31
Open
harrymove-ctrl wants to merge 2 commits into
Open
harrymove-ctrl wants to merge 2 commits into
harrymove-ctrl wants to merge 2 commits into
Conversation
A skill directory is only half a skill. Adding skills/<name>/ without registering it leaves an orphan package in the docs tree and renders the skill degraded on the site, and nothing caught it: skills are filesystem-discovered, so every missing registry entry has a silent fallback. A CATEGORY_MAP miss falls to "other"; a SKILL_PURPOSE miss falls back to a trigger phrase scraped from the description. Checks four registration points per skill directory -- the docs page, the docs README roster, CATEGORY_MAP, and SKILL_PURPOSE. Registry keys are written both quoted and bare in lib/skill-types.ts, so they are parsed out rather than grepped. enclave is allowlisted: it shipped without a docs page long before this check and closing that gap is its own change.
The registration check reads lib/skill-types.ts, docs/ai/skills/, and scripts/skill-registry-keys.py, none of which the workflow watched. It caught a skill added without registration, because that touches skills/. It would not have caught registration taken away from a skill that already had it -- dropping a CATEGORY_MAP entry or deleting a docs page leaves skills/ untouched, so the lint never ran.
harrymove-ctrl
force-pushed
the
fix/skill-lint-registration
branch
from
September 18, 2026 17:09
832b921 to
bc64cd3
Compare
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.
Why
A skill directory is only half a skill. Adding
skills/<name>/without registering it leaves an orphan package in the docs tree and renders the skill degraded on the site — and nothing caught it, because every missing registry entry has a silent fallback.Skills are filesystem-discovered (
lib/skills.ts:29), so an unregistered skill still renders.CATEGORY_MAPhas no entry, so it falls to"other".SKILL_PURPOSEhas no entry, soskillPurpose()falls back to the first quoted trigger phrase scraped off the description. Neitherbuildnorskill-lintsays a word.This is not hypothetical. Measured against the three open skill-adding PRs at the time of writing:
visualizewrite-cmk-skillcapability-map,trace-audit,elicit#28's were found by a human reading the diff. That is the part this check replaces.
What it does
Four registration points per skill directory:
docs/ai/skills/<name>.mdexistsdocs/ai/skills/README.mdCATEGORY_MAPentry inlib/skill-types.tsSKILL_PURPOSEentry inlib/skill-types.tsRegistry keys are written both quoted (
"delivery-ship") and bare (sync), so a grep for either form alone misses half of them.scripts/skill-registry-keys.pyparses the two object literals instead.Verification
Run against each branch, with the check wired in:
main— OKfeat/write-cmk-skill) — OKfeat/untrusted-input-boundary) — OKfeat/visualize-skill) — 4 violations, all realfeature/spec-knowledge-sharing) — 10 violations, all realBoth directions matter: a check that only ever passes proves nothing.
The one allowlist entry
enclaveshipped without adocs/ai/skills/page long before this check existed. It is allowlisted with a comment rather than silently exempted — closing that gap is its own change. The file's existing note applies: a new entry there must be a deliberate, reviewed decision, not a way to silence a fresh violation.