SYS/DEF
SKILL.md
The single file of an Agent Skill: YAML frontmatter (name, description, licence) + Markdown body. That is the spec, not a decorative README.
Definition
SKILL.md is the manifesto of a skill in the agentskills.io sense. Frontmatter requires a name (1–64, [a-z0-9-]+, no double hyphens) and a description (1–1024) precise enough that the agent knows when to load the body. Licence, compatibility, metadata, allowed-tools are optional. The body is the procedure.
Cursor fields (paths, icon, color…) are extensions. An honest validator accepts them with a note, and rejects an off-spec name even if the icon is pretty.
When it matters
On every skill created, forked, or reviewed in a PR. It is the file Shamalo’s library displays and the validator parses (js-yaml, not a regex). If the licence does not allow copying, we do not vendor the body — card + URL.
It is also the teaching surface: a custom Shamalo skill shows the format; it does not claim to be official.
Pitfalls
Indenting YAML by eye until the parser swallows a half-closed mapping. Novel-length description. Name in capitals or with spaces. Secrets in the body. Copying a skill whose LICENSE.txt says no.
Related terms
Related tool
Paste frontmatter and body: required fields, lengths, triggerable description: Open SKILL.md validator.