Frontmatter, exactly

The header of SKILL.md is read by a small hand-written parser, not a YAML library. This is deliberate: it supports what a skill header needs and throws on everything else, so a header is never silently mis-parsed into something you did not write.

What the parser supports

Form	Result
key: value	string
key: 42 / key: 1.5	number
key: true / key: false	boolean
key: [a, b, c]	list of strings
key: "quoted: value"	string, quotes stripped
# comment on its own line	ignored
key: value # comment	trailing comment stripped

Notes on the edges:

• A # only starts a comment when preceded by a space. key: c#1 keeps the #.
• A value that starts with " or ' is not comment-stripped at all.
• Only plain integers and decimals become numbers, which is why 1.2.0 and

2026-08-02 stay strings.

• A BOM and CRLF line endings are tolerated.

What the parser rejects, and the message

Message	Cause
missing frontmatter: file must start with a --- line	Anything before the opening ---, including a blank line
unterminated frontmatter: no closing --- line	No second ---
line N: indentation is not supported (no nested maps or block sequences)	A line starting with whitespace - nested map, or a - item list
line N: expected "key: value", got …	No colon, or a line starting with :
line N: invalid key …	Key is not [A-Za-z][A-Za-z0-9_-]*
line N: duplicate key …	The same key twice
line N: "key" needs an inline value (multi-line scalars are not supported)	Empty value, or | / >
line N: unterminated list - expected a closing ]	[a, b
line N: quoted entries are not supported in a list	[a, "b, c"] - the parser splits on every comma, so a quoted comma would tear in half
line N: empty entry at position K of the list	Trailing or doubled comma, [a, b,]

The list errors name the mistake where it is, rather than letting it surface one step later as a phantom empty tag.

Field rules

Checked after parsing, by the validator.

name

Must equal the folder name. The folder is the slug, and the slug must match ^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$ - lowercase, hyphens allowed inside, 3-64 characters, alphanumeric at both ends.

all and cli are reserved. The registry serves /install/all and /install/cli itself, so a skill by either name would shadow a real endpoint and give you a working command that did the wrong thing.

description

10-200 characters. One line, because the parser has no multi-line scalars. This is the highest-leverage field in the file; see writing-well.md.

version

^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$ - SemVer with optional pre-release and build metadata. 1.0.0, 2.0.0-rc.1, 1.0.0+build.5 all pass.

author

^[a-zA-Z0-9_.-]{1,40}$. This is a display field; ownership comes from the account whose token published it, not from this string.

license

An SPDX identifier, checked against a list. MIT, Apache-2.0, BSD-3-Clause, GPL-3.0-only, CC-BY-4.0, Unlicense, and so on. Not a free-text field, and not a URL.

tags

An inline list, 1-8 entries. Each matches ^[a-z0-9][a-z0-9.-]{0,31}$ - lowercase alphanumeric, . and - allowed after the first character, 32 characters max.

Tags are what devkit search and the catalogue filter on. Prefer a few accurate ones over eight hopeful ones.

status

Exactly one of stable, beta, deprecated.

deprecated is a signal to readers, not an enforcement - the skill stays installable. To actually withdraw a release, use devkit yank.

created / updated

Optional, YYYY-MM-DD. If updated is absent it defaults to created. The registry's own editor stamps these when it writes a skill, so the dates live in the file rather than being guessed at read time.

featured

Set by the registry. Putting featured: true in your own file does not feature your skill.

A header that uses everything legal

---
name: release-checklist
description: Use when cutting a release, tagging a version, or writing release notes for a service.
version: 2.1.0
author: chempa
license: Apache-2.0
tags: [release, ci, checklist]      # 1-8, lowercase
status: stable
created: 2026-01-04
updated: 2026-08-02
---