How to Write a SKILL.md

A SKILL.md packages procedural knowledge an agent should load only when a task calls for it. Writing one well is mostly about two things: a trigger description precise enough that the skill fires at the right moments, and a body organized so the agent pays for depth only when it needs depth. This guide covers both, plus the maintenance practices that keep a skill library trustworthy.

The Frontmatter Is the Product

A skill starts with YAML frontmatter, and the description field is the single most important line you'll write — it is all the agent sees when deciding whether to load the skill:

---
name: markupmarkdown
description: Google-Docs-style commenting on markdown documents.
  Lets agents and human reviewers collaborate on the same docs —
  read, comment, reply, resolve threads, and trigger AI revisions
  of a doc based on comments humans have approved.
---

Write the description in terms of tasks and trigger words, not features: “Use when the user asks to review, comment on, or ship a markdown document” beats “A document collaboration tool.” If a skill fires too often, the description is too broad; too rarely, too narrow. Tune it like a search query — empirically.

Structure for Progressive Disclosure

Organize the body in descending order of necessity. First: the mental model in a few sentences — what the agent is operating on and the vocabulary it needs. Second: the workflows for the most common tasks, each as a short numbered sequence. Third: the reference material — and once reference material grows past a screen or two, move it to separate files the skill links to (REFERENCE.md, an API schema, example payloads). The agent reads linked files only when a task requires them, which keeps the routine case cheap. Bundled scripts follow the same rule: a deterministic operation (parsing, format conversion, API pagination) belongs in a script the agent runs, not prose it re-derives every session.

Write for a Competent Stranger

The agent reading your skill knows nothing you didn't write down, and it will follow what you did write with disconcerting literalness. Three habits pay off. State preconditions (“requires a token with write scope; get one from the avatar menu”). Show one complete worked example per workflow — a real request and a real response teach more reliably than any amount of description. Mark the boundaries: what the agent should never do with this skill (“never push without explicit human approval”), because a skill without stated limits inherits whatever ambient permissions the session has.

Test It Like Software

A skill's test suite is a set of real tasks. Run each with the skill installed and confirm: it triggered when it should, it didn't when it shouldn't, and the agent's behavior actually matched the instructions. When an agent misuses your product's API despite a skill, that's a bug report against the skill — fix the wording that misled it. Publishing a skill for a live product? Serve it from the product itself so it can't drift from the deployment — markupmarkdown embeds its SKILL.md in the server binary and serves it at /SKILL.md, with a build-time test that fails when the repo copy and the embedded copy diverge.

Maintain the Library

Skill edits change agent behavior everywhere, so review them like code and prose at once: threaded comments on the exact sentence at issue, suggested edits applied in one click, checks that required sections exist and placeholder text doesn't, and a human approval gate before publication. That is the markupmarkdown loop — and since a skill library is just a folder of markdown in a repo, its markdown indexes give you the whole library on one reviewable page.