How to Write a SKILL.md: The Anatomy of a Real Agent Skill

Writing a skill takes ten minutes. Writing a skill that actually loads when it should — and stays out of the way when it shouldn't — is a different problem, and it's almost entirely about the first fifteen lines of the file.

A SKILL.md is deceptively simple: a folder, one markdown file, some YAML frontmatter. But the frontmatter is a routing decision. The agent reads only the name and description of every skill you have installed, and picks based on that text alone. If your description doesn't match the moment, the rest of your carefully written instructions never enter the context window.

This post takes a real skill apart line by line, then rebuilds the parts that matter: what goes in the frontmatter, how to write a description that triggers, how to structure the body so it survives being read mid-task, and what to bundle alongside it.

What a skill actually is

At heart:

my-skill/
├── SKILL.md          # required — metadata + instructions
├── scripts/          # optional — executable helpers
└── references/       # optional — docs loaded on demand

SKILL.md is the only required file. It has two parts — YAML frontmatter (the metadata an agent sees first) and a markdown body (the instructions, read only when the skill activates).

The mechanism behind that split is progressive disclosure, and understanding it explains every design choice below:

1. Discovery — at startup, the agent holds only each skill's name and description. Hundreds of skills cost very little context this way.
2. Activation — when a task matches a description, the agent reads the full SKILL.md.
3. Execution — the agent follows the instructions, reaching for bundled scripts or reference files as needed.

So the description does the work of an index card in a card catalogue: it must be accurate and scannable, because it is all the agent knows about your skill until it commits to opening it.

The anatomy, line by line

Here is a real skill from the hub — the core GSAP skill published by GreenSock, the people who make GSAP — in simplified form:

---
name: gsap-core
description: GSAP core API reference — .to(), .from(), .fromTo(), timeline
  basics, easing functions, stagger, and reduced-motion handling. Use when
  writing or debugging GSAP tweens, animating elements with JavaScript, or
  choosing an easing curve.
license: BSD-3-Clause
---

# GSAP Core

## Quick reference

...instructions...

Four fields, each doing a specific job:

name

The identifier. Short, lowercase, hyphenated, and stable — it's how the skill is addressed and how it appears in listings. Treat it like a package name: renaming it later breaks anyone who referenced it.

description — the field that decides everything

This is the trigger. The agent matches your task against this text, and nothing else, at discovery time. Compare two ways of describing the same skill:

❌ "A helpful skill for working with GSAP."

✅ "GSAP core API reference — .to(), .from(), easing, stagger. Use when writing or debugging GSAP tweens or choosing an easing curve."

The second one wins for three reasons:

• It names the artifacts. .to(), .from(), easing, stagger — the words that will literally appear in the user's request or the codebase the agent is looking at.
• It states the trigger explicitly. The "Use when…" sentence is a matching hint written the way users actually ask. Multiple triggers, comma-separated, widen the net.
• It says what it is in the first clause. "API reference" tells the agent this is a lookup skill, not a procedure — which changes how it will use the file.

A practical test: list five things a user might say that should activate this skill, and make sure each contains a phrase from your description. If a plausible request doesn't match any wording in the description, the skill will not fire.

Two more rules worth following:

• One description, one job. If a skill could apply to two very different tasks, it's two skills. A vague description covering both will match neither well.
• Put the trigger words in the description, not the body. The body is invisible at discovery time.

license and the rest

license declares how others may reuse the skill — worth setting if you publish it. Beyond that, the spec allows additional metadata (version, allowed tools, and whatever your harness supports), but name and description are the required pair, and they're what every compliant agent reads. Keep the frontmatter small: anything in there is context you pay for at startup, on every skill you have installed.

The body: write for someone mid-task

When the body loads, the agent is already working. It isn't reading for pleasure — it's looking for the step it needs right now. That shapes the structure:

Start with a one-line statement of what this skill does and when the instructions apply. If the agent activated you by mistake, that line lets it bail before wasting context.

Use headings that name decisions, not topics. "Choosing an easing curve" beats "Easing" — the agent is scanning for the decision in front of it.

Prefer procedures to prose. Numbered steps, decision tables, code blocks:

## Choosing an easing

| Situation | Ease |
| --- | --- |
| UI element entering the screen | `power2.out` |
| Element returning to rest | `power2.inOut` |
| Physics-like, playful | `back.out(1.7)` |
| Never use | `linear` for motion a person sees |

A table like this is a lookup the agent can answer in one pass. Two paragraphs describing the same thing take longer to parse and are easier to misread.

Include exact commands, paths, and signatures. The agent should never have to guess a flag name. "Run npm run lint -- --fix" is actionable; "run the linter with the fix option" invites a hallucinated flag.

Keep it as short as it can be. A skill is context, and context competes with the task. The GSAP skill's job isn't to teach animation theory — it's to answer "which API do I reach for?" in seconds. Depth belongs in bundled reference files (below), pulled in only when needed.

What goes wrong in bodies

Three failure modes show up in almost every weak skill I've read while curating the hub:

1. Vibes instead of workflow. "Make sure the animation feels good." The model already wants to do that. A skill earns its place by encoding how a skilled person decides — what they check first, what they rule out, which option they reach for and why.
2. Duplicated knowledge. Restating what the framework's docs already say at length. If the agent can look it up, your skill should say where to look and what to watch for — or compress the decision down to a table like the one above.
3. Hidden preconditions. Instructions that only work if some state exists — a flag enabled, a file present, an env var set. State the preconditions at the top, or the skill fails silently in the one context where it mattered.

Bundling files alongside

A skill folder can carry more than the one file, and the pattern that works is thin skill, deep references:

• SKILL.md — the routing and the core procedure. Read every time the skill activates.
• references/*.md — deep documentation the agent reads only when the instructions point at it.
• scripts/* — deterministic helpers the agent runs instead of improvising (a validator, a formatter, a scaffold).

The GSAP skill is exactly this shape: the body covers the common API, and points at separate files for plugins, framework integration, and performance detail. The agent pays for the core file once and drills in only where the task goes.

Scripts deserve special mention: a bundled linter or checker turns "please make sure this is right" into an exit code. Skills that ship a verification step catch their own failures — and a skill the agent can self-check is one it will trust on the tenth use, not just the first.

A checklist before you publish

Run through this before a skill leaves your machine:

• name is short, stable, and hyphenated.
• description names the artifacts a user would mention, and contains an explicit "Use when…" trigger.
• You can name five requests that should activate it — and each matches wording in the description.
• The body opens by stating what it does and when the instructions apply.
• Procedures are steps, tables, and exact commands — not paragraphs of advice.
• Preconditions and required setup appear before the first step.
• Deep material lives in references/, pointed at from the body.
• Anything checkable has a script or command that checks it.
• Total length is as short as the job allows.

The last one matters more than it looks. Every skill you install costs description context at startup and body context on activation. A tight skill is one you can afford to keep installed; a bloated one is one you'll delete — however good its advice.

Where it fits in the wider picture

Skills are one of three ways to extend an agent — alongside MCP servers and sub-agents — and they're the lightest of the three: a folder of text, no process, no protocol. If you're weighing which one you need, Agent Skills vs MCP vs Subagents walks through the trade-offs.

And once you've written one: the whole reason to publish a skill is that someone else can install it in two minutes. My agent skills hub indexes 90 skills across eight categories on GitHub — browse it to see how other people solve the same problems your skill is about, and if yours is missing, the index takes a pull request.