How to Write a Great SKILL.md File (With Examples)

A great SKILL.md file has two parts: a short YAML frontmatter block with a name and a description, and a markdown body with clear, step-by-step instructions. The description decides when an agent uses the skill; the body decides how well it does the job. Get both right and your agent will reach for the skill at the right moments and follow it reliably.

Below you will find the format, writing tips for each section, a complete example, and the mistakes that most often make skills fail.

A quick refresher: what a SKILL.md does

An agent skill is a folder that teaches an AI agent a specific task. The SKILL.md file is the entry point. Agents typically read only the name and description of every installed skill, then load the full file when a request matches. If you are new to the idea, start with our overview of what agent skills are.

That loading pattern shapes everything about how you should write the file. The frontmatter must be short and precise, because it is always visible. The body can be longer, because it is read only when needed.

The basic structure

Every SKILL.md follows the same shape:

---
name: your-skill-name
description: What this skill does and when the agent should use it.
---

# Title

Instructions in plain markdown.

The skill lives in a folder, usually named the same as the skill:

your-skill-name/
├── SKILL.md
├── reference.md      (optional)
└── scripts/          (optional)
    └── check.sh

Only SKILL.md is required. Everything else is optional supporting material.

Writing the frontmatter

The name

Keep the name short, lowercase, and hyphenated, like release-notes or api-error-handling. It should describe the job, not the team or the tool that wrote it. Many tools enforce length limits and character rules, so a plain, descriptive slug is the safest choice.

The description

The description is the most important line in the file. It is what the agent reads when deciding whether this skill fits the current request. A good description answers two questions:

1. What does the skill do?
2. When should the agent use it?

Compare these:

Weak description	Strong description
Helps with tests.	Writes and runs unit tests for this TypeScript project using Vitest. Use when adding features, fixing bugs, or when the user asks for tests.
Database stuff.	Creates and reviews SQL migrations safely. Use whenever a change touches the database schema or adds a migration file.
Writing helper.	Applies our product voice and terminology to user-facing text. Use when writing UI copy, release notes, or help articles.

The strong versions name concrete triggers (“when adding features”, “whenever a change touches the database schema”). Those trigger words are what help the agent match the skill to real requests.

Writing the body

The body is where you teach. Write it the way you would brief a capable new teammate who has never seen your project.

Lead with the goal

Open with one or two sentences about what success looks like. “The goal is a migration that can be applied and rolled back without data loss” gives the agent a yardstick for every later decision.

Use numbered steps for processes

If order matters, number it. Agents follow numbered steps closely, and it becomes easy to spot where something went wrong.

Be specific

Replace vague advice with exact actions:

• Instead of “run the tests,” write “run npm test and make sure it exits with no failures.”
• Instead of “follow our style,” write “use sentence case for headings and never use exclamation marks.”

Include a short example

One good input-and-output example often teaches more than a paragraph of rules. Keep it short and realistic.

List the gotchas

Write down what tends to go wrong: files that are generated and must not be edited, commands that need a flag, checks that are slow. This is exactly the knowledge an agent cannot infer.

Point to supporting files

If you have a long style guide or an API reference, put it in a separate file and link to it from the body, saying when to read it. That keeps SKILL.md focused and lets the agent load detail only when it is useful.

A complete SKILL.md example

Here is a full, realistic skill for writing database migrations. You can adapt the structure to almost any task.

---
name: safe-db-migrations
description: Creates and reviews database schema migrations so they can be applied and rolled back safely. Use whenever a change adds, removes or renames tables or columns, or when the user asks for a migration.
---

# Safe database migrations

The goal is a migration that applies cleanly, can be rolled back,
and never loses existing data.

## Steps

1. Read the current schema in `db/schema.sql` before writing anything.
2. Create a new migration file with the project's generator:
   `npm run migration:new -- <short-name>`
3. Write both the `up` and the `down` section. Never leave `down` empty.
4. For renames, add the new column, copy the data, then drop the old
   column in a separate, later migration.
5. Run `npm run migrate` and then `npm run migrate:rollback` to prove
   both directions work.
6. Run `npm test` and confirm it passes.

## Rules

- Never edit a migration that has already been merged. Create a new one.
- Add an index for every new foreign key column.
- New columns on large tables must be nullable or have a default.

## Example

Request: "Add a `last_login_at` timestamp to users."

Good migration:
- up: add nullable column `last_login_at` to `users`
- down: drop column `last_login_at` from `users`

## Gotchas

- `db/schema.sql` is generated. Do not edit it by hand; it updates
  when migrations run.
- If `migrate:rollback` fails, fix the `down` section before
  continuing. Do not delete the migration to make the error go away.

For naming conventions and index rules in detail, read
`reference/conventions.md`.

Notice what this example does well:

• The description names the triggers: adding, removing, or renaming tables or columns.
• The steps include exact commands and a verification loop.
• The rules are short and testable.
• The gotchas capture hard-won project knowledge.
• The reference file keeps extra detail out of the main file until it is needed.

Common mistakes to avoid

Most skills that “don’t work” fail for a handful of reasons:

• The description is too vague. The agent never realizes the skill applies. Add concrete triggers.
• The description is too broad. The skill fires for everything. Narrow it to one job.
• The body is a wall of prose. Break it into steps, rules, and examples.
• It assumes hidden context. Spell out file paths, commands, and names.
• Everything is in one file. Move long references into separate files and link to them.
• It is never tested. Always try the skill on a real request before relying on it.

How to test and improve a skill

Treat a skill like code: write it, try it, refine it.

1. Ask the agent to do a task that should trigger the skill. Check that it loads the skill.
2. Ask for something that should not trigger it. Check that it stays out of the way.
3. Read the result against your rules. Where the agent drifted, make that instruction more explicit.
4. Repeat until the agent behaves the way an experienced teammate would.

Once you have one solid skill, more ideas tend to follow. Our list of essential skills for AI coding teams is a good source of inspiration, and the same briefing habits apply when you write better briefs for coding agents.

If you run a team of agents in BotQuarters, you can add skills like this to teammates from the skill library in one click.

FAQ

What should go in the SKILL.md frontmatter?

At minimum, a name and a description in YAML between two --- lines. The name is a short, hyphenated identifier, and the description says what the skill does and when to use it. Some tools support extra optional fields, so check your agent’s documentation before adding more.

How long should a SKILL.md file be?

Long enough to teach the task clearly, and no longer. Keep the main file focused on steps, rules, and a short example, and move long reference material into separate files that the body links to. That way the agent loads detail only when it needs it.

Why isn’t my agent using my skill?

The usual cause is the description. If it is vague, the agent cannot tell when the skill applies; if it is too broad, it may be skipped in favor of a better match. Rewrite it to state concrete triggers, and confirm the skill folder is in the location your agent tool expects.

Can a skill include scripts?

Yes. A skill folder can include scripts the agent runs, such as validators or converters. Mention each script in SKILL.md with what it does and when to run it, so the agent knows it exists and uses it at the right step.