Anatomy of a great SKILL.md

A skill is one file, and the agent that runs it has never met you. It has your file and a task, and inside the first second it decides whether this is worth following or noise to route around. Everything you know about the work is either written down there or it may as well not exist. That is the whole game. The skills people keep installed and the ones they uninstall by lunch are separated by nothing but how that one file is written.

We see both kinds cross the counter every day. The good ones share an anatomy, and it is not a long list. Here is what earns a file its place on the shelf.

The one-liner is a trigger, not a label

On Generalized a skill's description runs 10 to 200 characters, and it is the most overworked sentence in the file. It is the first thing the agent reads, and it does two jobs at once. It tells the model when to reach for the skill and when to leave it alone. And when the skill installs, that same line gets quoted back to the user as the reason it landed. A description that reads "helps with pull requests" fails both jobs at once: the agent cannot tell whether the task in front of it qualifies, and the user learns nothing about what just showed up in their project.

So spend the characters on the trigger, not the topic. "Triage an incoming PR — label, assign, flag risky diffs; use when a PR opens, skip drafts" earns its length. It names the work and the boundary in one breath. A model can match a task against it, and a human reading the install line knows exactly what arrived. The one-liner is the door; write it so the right tasks walk through and the wrong ones keep going.

Encode judgment, not knowledge

The body of a SKILL.md caps at 64KB — room for a short essay, nowhere near room for a manual, and that ceiling is doing you a favor. The instinct, staring at a blank file, is to explain the domain. Resist it. The model already knows the domain; it has read more about pull requests, CSS, and Postgres than you ever will. What it cannot guess is the part that lives only in your head: the order you run your checks in, the default you reach for when the spec goes quiet, the thing you look at first because it burned you once.

Generic instructions are already free — every capable model ships with a heap of them. Your way of doing the work is the scarce part, and it is the only thing worth 64KB. Write the sequence, not the subject. Write "read the diff before the description, because descriptions lie" instead of a paragraph on what a diff is.

A skill that could have been written by anyone will be replaced by one that couldn't.

That holds whether the reader is a person or a model. The files that survive read like their author sounds — specific, a little stubborn, honest about the one case where the rule breaks. A skill with a point of view is a skill someone can trust to hold that view when they are not in the room.

Refusals are taste, written down

The most under-written section of most skills is the one that says stop. A file that only knows how to say yes becomes a liability the first time the task drifts past its competence — and tasks always drift. So name what the skill will not do, out loud, in the file. The triage skill triages and never merges. The refactor skill never touches markup it cannot see rendered. The migration skill writes the migration and refuses to run it against production.

Refusals are taste in its most concentrated form. They are the line between a colleague you hand the keys to and one you have to stand behind all afternoon. Draw the line explicitly and the agent holds it when you are not watching, which is the entire point of writing the skill down instead of doing the work yourself. A good refusal section is short, and it is the part experienced authors write first.

The shape agents actually fetch

The file's shape follows from how it gets installed, so it helps to know what happens. An agent GETs the skill's manifest and reads the description, the author, the proof, and a list of files — each one carrying its byte size and a sha256. Then it fetches every file, writes it verbatim into the project's skills directory, and checks each one against its hash. SKILL.md is the file it reads first, and it has to sit at the skill's root. That is not a style preference; the whole thing is named for it, and the publish gate rejects a skill that ships without one.

A skill carries at most 20 files, 64KB each. Most great ones use exactly one. When you do reach for more, they are supporting cast — a template the SKILL.md points the agent at, a schema, a worked example — and they live at nested paths like templates/label-map.md. The rule of thumb: if a second file is not something the SKILL.md tells the agent to go open, it does not belong in the box. Every extra file is a thing the reader has to hold in their head.

Here is a whole file, small on purpose:

---
name: pr-triage
description: Triage an incoming PR — label, assign, flag risky diffs. Use when a PR opens or gets new commits; skip drafts.
---

# PR triage

## When to reach for this
A pull request just opened or picked up new commits. Not for
drafts, not for merge-queue chores, not for your own PRs.

## Order of checks
Read the diff before the description — descriptions lie.
Size it: under 50 lines is a glance, over 500 is a meeting.
Label by the paths touched. Assign whoever last owned them.

## Defaults
Reach for the smallest safe label. One reviewer, not three.
When the diff and the title disagree, trust the diff.

## What this refuses
Never approve. Never merge. You triage; a human decides.
See templates/label-map.md for the label vocabulary.

Nothing in there explains what a pull request is. Every line is a decision the author would have made, set down in the order they would have made it. That is the density a great SKILL.md is aiming for.

The uninstall test

Retention is the only honest grade, and it is the one the shelf keeps. A skill that gets installed and stays did the job the way its author would have. A skill that gets deleted by lunch fired at the wrong time, or explained where it should have decided, or said yes where it should have said no. Every section above is the same instruction seen from a different angle: put the part of the work that only you would have gotten right into the one file the agent reads, and cut everything a capable model already knows.

Do that, and the file earns its place. The install sticks, the number climbs, and your handle is on the line the user reads when it lands. That is the difference between a skill on the shelf and a skill in the bin — and it all fits in a page.