skills/skillsctl-usage.md has no YAML frontmatter. It starts straight at the H1:
# skillsctl - Skill Registry CLI
https://github.com/nebari-dev/skillsctl/blob/main/skills/skillsctl-usage.md
Install it and you get ~/.claude/skills/skillsctl-usage/SKILL.md with that same content, no frontmatter block. Claude Code still registers the skill, but it falls back to the H1 as the description, so it shows up as the bare string "skillsctl - Skill Registry CLI". Since the description is what drives skill selection, this one won't reliably trigger. The other 7 skills in the registry all have proper frontmatter with trigger phrases.
Bit of an own goal, since the skill has a whole "Finding skillsctl" section meant to stop agents from failing to locate the binary, and it's the skill least likely to fire when that happens.
The reason this isn't caught anywhere: skillpkg.Validate checks tarball size limits, rejects symlinks/hardlinks, blocks absolute paths and parent traversal, and requires SKILL.md at the tarball root, but it never looks inside the file.
https://github.com/nebari-dev/skillsctl/blob/main/internal/skillpkg/validate.go#L23
So nothing stops anyone publishing a skill that agents can't select properly. The registry metadata makes it worse to spot: name and description come from backend/internal/seed/skills.go for the seed, and from --name/--description on publish, both separate from the file's own frontmatter. skillsctl explore shows a perfectly good description while the installed file is deficient.
Two things, and I think they're separable:
- Add frontmatter to
skills/skillsctl-usage.md and re-seed. Small fix.
- Should
Validate parse and require frontmatter (name + description at minimum) on publish?
For 2, I can see the argument either way. Enforcing it means the registry can't serve a skill that won't load properly, which seems like the point of having a validator. But it's a breaking change for anything already published without it, and it puts the CLI in the business of knowing the skill format rather than just moving tarballs around. #47 is heading toward treating the agentskills.io frontmatter as the spec, so if that lands then validation follows from it fairly naturally.
Observed on skillsctl-usage@0.2.4, CLI v0.2.0.
skills/skillsctl-usage.mdhas no YAML frontmatter. It starts straight at the H1:https://github.com/nebari-dev/skillsctl/blob/main/skills/skillsctl-usage.md
Install it and you get
~/.claude/skills/skillsctl-usage/SKILL.mdwith that same content, no frontmatter block. Claude Code still registers the skill, but it falls back to the H1 as the description, so it shows up as the bare string "skillsctl - Skill Registry CLI". Since the description is what drives skill selection, this one won't reliably trigger. The other 7 skills in the registry all have proper frontmatter with trigger phrases.Bit of an own goal, since the skill has a whole "Finding skillsctl" section meant to stop agents from failing to locate the binary, and it's the skill least likely to fire when that happens.
The reason this isn't caught anywhere:
skillpkg.Validatechecks tarball size limits, rejects symlinks/hardlinks, blocks absolute paths and parent traversal, and requiresSKILL.mdat the tarball root, but it never looks inside the file.https://github.com/nebari-dev/skillsctl/blob/main/internal/skillpkg/validate.go#L23
So nothing stops anyone publishing a skill that agents can't select properly. The registry metadata makes it worse to spot: name and description come from
backend/internal/seed/skills.gofor the seed, and from--name/--descriptionon publish, both separate from the file's own frontmatter.skillsctl exploreshows a perfectly good description while the installed file is deficient.Two things, and I think they're separable:
skills/skillsctl-usage.mdand re-seed. Small fix.Validateparse and require frontmatter (name+descriptionat minimum) on publish?For 2, I can see the argument either way. Enforcing it means the registry can't serve a skill that won't load properly, which seems like the point of having a validator. But it's a breaking change for anything already published without it, and it puts the CLI in the business of knowing the skill format rather than just moving tarballs around. #47 is heading toward treating the agentskills.io frontmatter as the spec, so if that lands then validation follows from it fairly naturally.
Observed on
skillsctl-usage@0.2.4, CLI v0.2.0.