Four skills declare a frontmatter name: that does not match their directory

Author: gkinterCreated Sep 8, 2026Updated Sep 8, 2026

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