Skill Creator frontmatter guidance conflicts with sample and validator

Open 💬 0 comments Opened Jun 1, 2026 by bar-d

What happened?

The bundled Skill Creator sample appears to give conflicting guidance about allowed SKILL.md frontmatter fields.

At the top of the same sample skill, the frontmatter includes:

metadata:
  short-description: Create or update a skill

Later, the authoring guidance says:

Do not include any other fields in YAML frontmatter.

The bundled quick_validate.py script also explicitly allows additional frontmatter keys beyond name and description, including metadata, license, and allowed-tools.

Expected behavior

The Skill Creator guidance should align with the bundled sample and validator: either document the allowed optional frontmatter fields, or update the sample/validator if name and description are intended to be the only supported keys.

Additional context

I searched open issues and PRs for terms including skill-creator, metadata frontmatter, quick_validate, and allowed-tools, and did not find an existing open item that appears to cover this guidance conflict.

View original on GitHub ↗