SKILL.md is the file format behind Agent Skills. It has two halves and they do completely different jobs. The YAML frontmatter carries a name and a description, and those sit in the agent's context for the whole session, for every skill installed. The markdown body below carries the actual instructions and loads only when the agent selects that skill mid-task. This split is called progressive disclosure, and once you understand it, most of the practical advice about writing skills follows from it.
The consequence people miss is that the description is not documentation, it is the selection interface. It is the only text the agent sees when deciding whether to open your file. A description written for a human reader, explaining what the skill contains, gives the model nothing to match a task against. A description written for selection says when to use this skill and when not to, in the vocabulary the task will arrive in. Most of the difference between a skill that fires and a skill that sits inert is in those two or three lines.
The body is where the token cost lives, so it should read like a procedure rather than an essay. Concrete steps, named tools, explicit constraints, and worked examples earn their space. Background, motivation, and history do not, because by the time the body loads the agent has already decided to act. Skills that bundle reference material into the body pay for it on every invocation.
Compliance with the published specification is worse than most teams assume. A static-analysis census of 138,133 public skill files found 89.3% violate at least one rule in the official Agent Skills specification, most commonly around description quality and frontmatter structure. That number is not an argument that the spec is fussy. It is a reasonable proxy for how many public skills will fail to be selected when it matters, since the rules that get broken most are the ones governing the text selection depends on.
There is also a trust dimension the format does not address. A SKILL.md is unsigned plain text that an agent will follow with roughly the authority of a user instruction, and it usually arrives by being copied out of a public repository. Nothing in the file format establishes who wrote it or whether the copy you have matches what they wrote.
Why It Matters
Writing a SKILL.md is the cheapest way to change what an agent reliably does, and the cheapest way to waste tokens on a file that never gets selected. The frontmatter-versus-body split decides both outcomes, so knowing which half does what is the difference between a library your agents actually use and a folder of well-intentioned markdown nobody reads. For anyone maintaining more than a handful, it is also the unit of review: a skill you cannot describe in two lines is usually two skills.
Example
A team writes a skill for incident response and gives it the description "Comprehensive guide to our incident management process, covering severity levels, escalation paths, and postmortem requirements." It almost never fires, because no incoming task looks like that sentence. They rewrite it as "Use when an alert fires, a service is degraded, or the user mentions an outage, incident, or sev. Do not use for planned maintenance." Same body, same 1,200 tokens, and the skill starts getting selected on the tasks it was written for.