How to Write a SKILL.md File (Step by Step)

Writing your first AI agent skill is simpler than it sounds. A SKILL.md is just a markdown file with a little structure. Here is exactly how to write one, step by step, with a complete working example.

Step 1: Create the Folder

A skill is a folder, not just a file. Make a folder named after your skill — say code-reviewer — and put a SKILL.md inside it. The folder can later hold scripts or resources, but to start, the single file is enough.

Step 2: Write the Frontmatter

At the top of SKILL.md, add YAML frontmatter between two lines of three dashes. It needs two fields: a name (short, lowercase, hyphenated) and a description (what the skill does and, crucially, when to use it).

Step 3: Write the Body

Below the frontmatter, write plain markdown instructions. Be concrete: the steps to follow, the order to do them in, the conventions to apply, what to check. Think of it as the note you would leave a capable colleague taking over the task.

A Complete Working Example

Here is a full code-reviewer skill. The frontmatter declares the name and a description that lists how people actually ask for reviews. The body gives an ordered checklist: correctness first, then security, then style, then tests — with an instruction to report findings grouped by severity, citing file and line.

The Part People Get Wrong

The most common mistake is rushing the description. People write something narrow like "Reviews pull requests," then wonder why the skill never fires when they ask to "check this file." The description must match the words you actually use — list the synonyms, describe the trigger naturally. It deserves more attention than the entire body.

From One Skill to a Library

Writing one skill teaches you the structure. The real payoff comes from a personal library of them — built, tested and refined — that improves every AI agent you use.