Write SKILL.md
Write valid, portable frontmatter
Create the required name and description fields, then add optional metadata only when it communicates a real constraint.
10 minute lesson
Every skill needs a SKILL.md file with YAML frontmatter. The portable minimum is name and description.
Start the project file like this:
---
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 current specification also defines optional fields such as license, compatibility, and metadata. Use compatibility only when the workflow needs a particular environment, package, or network capability. Do not copy optional fields just because another skill has them.
allowed-tools is experimental and support varies. Treat it as host-dependent convenience, not the only security boundary. A portable skill should still state its behavioral limits and work with the host’s permission model.
Validate the frontmatter before writing twenty pages beneath it. Check that the name matches the directory and uses the allowed form. Parse the YAML. Confirm the description is non-empty and within the specification limit.
Create one deliberately broken copy with a mismatched name or invalid YAML. Run your chosen validator and keep the error as evidence that the check can fail.
Lesson completed