How to Write a SKILL.md File an Agent Actually Follows

Quick answer
Create a folder whose name is lowercase and hyphenated, then add a SKILL.md inside it.
Start with YAML frontmatter containing name and description; the description decides whether the skill ever loads.
Write the body as numbered steps, each with the exact command to run and the result that proves it worked.
Put reference material in separate files in the same folder and link them, rather than padding the main file.
Test with a realistic prompt, then delete any step the agent ignored — untested instructions are the ones that mislead.

What is the minimum valid SKILL.md?

A folder, a SKILL.md, and two frontmatter fields. The name must be lowercase letters, numbers, and single hyphens, and it must match the directory name. The description is free text, but it should name the task that triggers the skill and the files or systems involved.

Optional fields such as licence, compatibility, and metadata are useful for shared skills; an experimental allowed-tools field can restrict which tools the skill may use. Omit optional fields you do not need, because every field is something a future reader has to interpret.

mkdir -p .agent/skills/add-migration
cat > .agent/skills/add-migration/SKILL.md <<'EOF'
---
name: add-migration
description: Create and verify a database migration for the Postgres schema in this repository. Use when a change adds or alters a table, column, or index.
---

1. Confirm the target schema change and the tables it touches.
2. Generate the migration with the project's migration tool.
3. Run it against a disposable database.
4. Verify the resulting schema and that the down migration runs.
EOF
ls .agent/skills/add-migration/SKILL.md

How do you write a description that triggers reliably?

Name the task in the words a person would use, then name the trigger conditions and the artefacts involved. A description like “helps with databases” will either never fire or fire constantly. A description like “create and verify a Postgres migration when a change adds or alters a table, column, or index” gives the model a decision it can make.

Avoid duplicating another skill’s trigger. If two skills both claim migration work, the agent has to guess, and guesses are unstable across runs. Distinct descriptions are a routing table, and they need the same care as routing rules.

What belongs in the body?

Numbered steps, the exact command for each step, and a success check. State the tool to use, the arguments that matter, and what output means the step worked. If a step is destructive, say which environment it may run against and which it must not.

Long reference material — a schema, a list of accepted labels, a style guide — belongs in sibling files that the skill points to. That keeps the loaded part short and makes the reference independently reviewable.

How do you verify the skill actually works?

Run it against a real task in a scratch branch and watch which steps the agent skips. A step that says “ensure the tests pass” without a command is usually skipped, and a step that names an ambiguous file is usually resolved wrongly.

Then tighten the wording and rerun. A skill is a program written in prose, so it needs the same treatment as code: a test case, a revision, and a reviewer who did not write it.

Where this bites vibecoders
An AI assistant asked for a skill will produce something that sounds authoritative and contains no commands. It will also cheerfully describe an idealised workflow the repository does not support. Replace every vague instruction with the exact command from your AGENTS.md, and delete the steps that describe work nobody does.

Where AI coding assistants get this wrong

Writing a description that summarises the skill instead of the task that should load it.
Putting several unrelated procedures in one skill so the agent half-follows all of them.
Using “make sure” or “ensure” without a command that proves it.
Hardcoding paths that exist only on the author’s machine.
Adding a script the skill never tells the agent to run.
Skipping the test run, so a broken trigger ships unnoticed.

Checklist

Name the folder and the skill identically, lowercase and hyphenated.
Write a description with the task, the trigger, and the artefacts.
Give each step one command and one success check.
Name the environment each command may run against.
Move long reference material into sibling files.
Test with a realistic prompt and remove steps the agent ignored.

FAQ

How long should a SKILL.md be?

Short enough that the agent reads all of it. If the procedure needs more than a page, the steps are probably too coarse or the reference material is in the wrong place. Move detail into sibling files and keep the main file to the sequence and its checks.

Can a skill include scripts?

Yes, and the scripts should be referenced by relative path from the skill folder. The agent runs them with the session’s permissions, so review them as code. A script that is not mentioned in the steps will not be run.

Should skills be committed to the repository?

Project skills that encode how the repository works should be committed, so changes are reviewable and every checkout behaves the same. Personal preferences belong in a user-level directory. Committing team skills is also how they get tested by more than one person.

Why does my skill not trigger?

Usually the description does not match the wording of the request, or another skill claims the same task. Rephrase the description around the user’s vocabulary, and check that no other skill overlaps. A skill whose name and description both describe the mechanism rather than the task is easy to miss.