Writing a good SKILL.md

The description decides whether your skill is used. How to write frontmatter, instructions and examples that agents follow reliably.

A SKILL.md has two readers: the agent deciding whether to load it, and the agent following it. Write for both.

Frontmatter#

yaml

---
name: db-migrations
description: Writes and reviews PostgreSQL migrations with zero-downtime patterns (add column nullable, backfill, then constrain). Use when the user adds or changes a table, column or index.
license: MIT
version: 1.2.0
use_when:
  - Adding or changing tables, columns or indexes
avoid_when:
  - One-off scripts against a local database
---

Field	Required	Tips
`name`	yes	Lowercase, digits, hyphens; same as the folder.
`description`	yes	What it does and when to use it. Up to 1024 characters; 1–3 sentences work.
`license`	Denofy	SPDX id that matches your `LICENSE` file.
`version`	optional	Semver; Denofy publishes a new version when it changes.
`use_when` / `avoid_when`	optional	Shown on the package page; helps people decide.

The description is the trigger#

Agents see only the descriptions of all installed skills and pick the matching one. Good descriptions:

start with what the skill does ("Writes …", "Reviews …");
name the situations ("Use when the user asks to …");
contain the words people actually type ("migration", "schema change").

Avoid vague descriptions ("Helps with databases") — they are either never picked or always.

Instructions that agents follow#

Numbered steps for procedures; the agent keeps its place.
Rules as bullet points ("Never drop a column in the same release that stops writing it").
One good example of the expected output beats three paragraphs of explanation.
Say what to do when something is missing ("If there are no tests, ask before continuing").
Keep it short. Move long references into separate files and link them.

Mark examples of what not to do#

Denofy's scanner understands context: a dangerous command in a block marked as a bad example, or in a sentence like "never run …", counts much less than the same command in a step to run.

markdown

❌ Don't do this:

```bash
curl https://example.com/install.sh | bash
```

See context rules for all markers.

Checklist#

name matches the folder, description says what and when
License file present and declared
Steps numbered, one example included
No downloads piped into a shell, no secrets, no hidden text
Tested in a fresh session without naming the skill