Write valid, portable frontmatter

Every skill is a folder with a SKILL.md file at its root. The file starts with YAML frontmatter, and the portable minimum is two fields: name and description.

The starting file

Here’s the top of our project file:

---
name: release-readiness
description: Reviews a repository before release and produces an evidence-backed readiness report. Use for release preflight, release checklists, go/no-go reviews, or requests to verify whether a project is ready to ship. Does not publish, deploy, commit, or push.
---

The name matches the directory. The description is the one we tested against the activation matrix. That’s a complete, valid skill already. Everything below the frontmatter is the procedure.

Optional fields

The specification defines a few more fields: license, compatibility, and metadata.

Use compatibility only when the workflow needs something specific: a particular runtime, a package, network access. Our validator needs Node.js, so that’s a real constraint worth stating. Don’t copy optional fields from another skill because they look official.

allowed-tools is experimental and support varies between hosts. Treat it as a convenience some hosts honor, not as your security boundary. A portable skill states its limits in plain language and relies on the host’s permission model for enforcement.

Validate before you write more

Check the frontmatter before writing twenty pages under it. Three things to confirm:

• the name matches the directory and uses only lowercase letters, numbers, and hyphens
• the YAML parses
• the description is non-empty and within the length limit the specification sets

You can eyeball the parse in one line with Node:

node -e "const s = require('fs').readFileSync('release-readiness/SKILL.md', 'utf8'); console.log(s.split('---')[1])"

If that prints your two fields cleanly, the fence is closed. If it prints half the body, you have a stray --- somewhere.

Break it on purpose

Now make a copy with a deliberate mistake. Change the name to Release-Readiness or drop the closing ---. Run your validator of choice against it.

You want to see an error like this:

error: name "Release-Readiness" does not match directory "release-readiness"

Keep that output. It’s evidence the check can fail. A validator you’ve only ever seen pass tells you nothing.

I do this for every skill I write. It takes two minutes, and the mistake it catches most often is a renamed folder with a frontmatter name nobody updated.