Four skills declare a frontmatter name: that does not match their directory
Four skills in this repo declare a frontmatter name: that does not match their directory name. The other five match, so this looks like an oversight rather than a convention.
| directory | frontmatter name: |
|---|---|
skills/composition-patterns |
vercel-composition-patterns |
skills/react-best-practices |
vercel-react-best-practices |
skills/react-native-skills |
vercel-react-native-skills |
skills/react-view-transitions |
vercel-react-view-transitions |
For contrast, these five already agree: deploy-to-vercel, vercel-cli-with-tokens, vercel-optimize, web-design-guidelines, writing-guidelines.
Reproduce against main:
for d in skills/*/; do
n=$(sed -n 's/^name:[[:space:]]*//p' "$d/SKILL.md" | head -1)
[ "$n" = "$(basename "$d")" ] || echo "$(basename "$d") declares $n"
done
Why it bites
Runtimes disagree about which of the two strings is a skill's identity. Ours (a DSH-based fleet) keys identity on the frontmatter name, while the packaging layer that links skills into a bundle keys on the directory path — so a skill whose two names differ is listed under one name and looked up under the other, and ends up reachable under neither. We hit this on all four: they were installed, mounted and never resolvable, silently, in every session that carried them. Anything else that pairs a directory-based manifest with name-based resolution (or the reverse) will see the same.
It also makes the skills hard to reference in docs and prompts: a reader who sees the directory writes composition-patterns, and that name does not exist.
Suggested fix
Either direction works as long as the two agree; renaming the four name: values to match their directories is the smaller change and keeps every existing path, link and git history intact:
skills/composition-patterns/SKILL.md -name: vercel-composition-patterns +name: composition-patterns
skills/react-best-practices/SKILL.md -name: vercel-react-best-practices +name: react-best-practices
skills/react-native-skills/SKILL.md -name: vercel-react-native-skills +name: react-native-skills
skills/react-view-transitions/SKILL.md -name: vercel-react-view-transitions +name: react-view-transitions
If the vercel- prefix is deliberate (to namespace against generic names like react-best-practices), renaming the four directories instead would be just as good — and applying the prefix consistently to all nine would be better still. A CI check that asserts name == basename(dir) for every skills/*/SKILL.md would keep it from drifting back.
Happy to send a PR for whichever direction you prefer.
Source: vercel-labs/agent-skills