fix: add YAML frontmatter to all SKILL.md files, and validate it in CI - #7
Merged
Conversation
…lidate in CI 28 of 39 SKILL.md files had no YAML frontmatter. The README has always documented it as required, so this was a repo consistency gap rather than a design decision, and nothing caught it. The consequence was not cosmetic. `npx skills` and OpenCode both key off `name` and `description`, and when those are missing they SKIP the skill silently. A user installing the collection got a partial install with no error explaining which skills were dropped or why. Reported by Jerry Gapinski, who hit it running the collection through OpenCode. Every description here comes from skills.json, which already carried a real description for all 39. Nothing was invented: the generator fails loudly rather than writing a placeholder if a skill is missing from the catalog or its description is blank. Frontmatter matches the convention already used by the 11 compliant files: `name` is the directory SLUG (not the display name, since that is what installers resolve against), a quoted single-line `description`, `license: MIT`, and a `metadata` block with author, version, mcp-server and category. scripts/validate-skills.mjs now checks, per skill: - SKILL.md exists and opens with a frontmatter block - `name` is present AND equals the directory slug - `description` is present and long enough to help an agent choose - the skill has a skills.json entry, warning when descriptions have drifted and repo-wide, that every skills.json entry points at a directory that exists. Wired into CI on push and PR. Verified it actually catches the regression: removing the frontmatter from one file exits 1, restoring it exits 0. A guard nobody has seen fail is not a guard. Three pre-existing warnings remain, where SKILL.md and skills.json descriptions have drifted apart on files that already had frontmatter. Left as warnings rather than errors, and deliberately not "fixed" by overwriting one with the other, since choosing which is correct is an editorial call.
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
1 participant
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.
28 of 39
SKILL.mdfiles had no YAML frontmatter. The README has always documented it as required, so this was a repo consistency gap and nothing caught it.The consequence was not cosmetic:
npx skillsand OpenCode both key offnameanddescription, and when those are missing they skip the skill silently. Installing the collection gave a partial install with no error saying which skills were dropped.Reported by Jerry Gapinski, who hit it running the collection through OpenCode.
What changed
skills.json, which already had one for all 39. Nothing invented: the generator fails loudly rather than writing a placeholder.nameis the directory slug (what installers resolve against), quoteddescription,license: MIT, and ametadatablock.scripts/validate-skills.mjschecks frontmatter presence, thatnameequals the directory slug, thatdescriptionis usable, and thatskills.jsonand the directories agree.Verified
Removing frontmatter from one file makes the validator exit 1; restoring it exits 0. A guard nobody has seen fail is not a guard.
Three pre-existing warnings remain where
SKILL.mdandskills.jsondescriptions have drifted on already-compliant files. Left as warnings, not silently overwritten, since picking the correct one is an editorial call.