How to write a SKILL.md: structure, fields and examples

· 4 min read

A SKILL.md file turns something you keep explaining to an AI agent into something it can load whenever the job comes up. It is plain markdown with a small block of frontmatter at the top. This guide covers the layout, the fields, and the habits that make a skill get used.

The format is the open Agent Skills specification, which Claude Code, GitHub Copilot and OpenAI Codex all read in one form or another.

What a skill is

A skill teaches an agent how to do one job well: review a pull request, write release notes, fill in a PDF form. The agent reads each skill’s name and description up front and loads the full instructions only when the task matches. That is why the description matters more than anything else in the file.

The folder layout

Every skill is a folder named after the skill. Only SKILL.md is required:

skills/
  code-review/
    SKILL.md          required: frontmatter and instructions
    references/       optional: documentation read only when needed
      checklist.md
    scripts/          optional: code for exact, repeatable steps
      count-lines.py
    assets/           optional: templates and data used in the output
      report-template.md

Agents read references/ files on demand, run scripts/ for steps that must be exact, and copy from assets/. Mention each of them in SKILL.md so the agent knows when to reach for it.

The frontmatter fields

The block between the two --- lines at the top holds the skill’s metadata.

Field Required Rules
name Yes 1 to 64 lowercase letters, numbers and single hyphens. It becomes the folder name.
description Yes Up to 1024 characters. Say what the skill does and when to use it.
license No A licence name, for example MIT.
compatibility No Up to 500 characters on environment needs, such as “Requires Node.js 22 and network access”.
allowed-tools No Tools the skill may use without asking, separated by spaces.

Two skills in the same project must not share a name, or their exported files would overwrite each other.

Write a description that gets the skill used

The description is the only part the agent sees before deciding to load the skill. Weak descriptions describe the topic; strong ones describe the trigger.

Weak: Helps with code review.

Strong: Reviews a code diff for bugs, security problems and unclear code.
Use when the user asks to review a pull request, a diff or recent changes.

A good rule: include a phrase like “Use when the user asks to…” and name the situations, file types or keywords that should bring the skill in.

Write the body

Under the frontmatter, write instructions the way you would brief a capable colleague who has never seen your project. A reliable structure:

  1. Title and overview: one or two sentences on the goal.
  2. When to use: the situations that should trigger the skill, and when not to.
  3. Steps: a numbered process the agent follows.
  4. Rules: constraints and things to avoid.
  5. Example: one input and the output you expect.

Here is a small complete skill:

---
name: code-review
description: Reviews a code diff for bugs, security problems and unclear code. Use when the user asks to review a pull request, a diff or recent changes.
---

# Code review

Review the changes the user points to and report problems in order of severity.

## When to use

- The user asks for a review of a diff, branch or pull request.
- Do not use it to write new code.

## Steps

1. Read the whole diff before commenting on any part of it.
2. List bugs and security problems first, then unclear code, then style.
3. For each finding, name the file and line and suggest a fix.

## Rules

- Only report problems you can point to in the diff.
- Keep each finding to three sentences or fewer.

Keep SKILL.md short

Keep SKILL.md under about 500 lines. When one section grows past roughly 60 lines or 700 words, move it into a file in references/ and leave a link behind:

For the full checklist, read `references/checklist.md`.

A reference file over about 300 lines should start with a table of contents so the agent can jump to the part it needs.

Check it before you ship

  • The name is lowercase with single hyphens and matches the folder.
  • The description says when to use the skill.
  • Every file in references/, scripts/ and assets/ is mentioned in SKILL.md.
  • No secrets, keys or private notes are in any file.

Build one with blocks

Skill Builder assembles a SKILL.md from blocks such as overview, when to use, steps and rules, previews the markdown as you go, and checks the fields above for you. Start from a template in the library, or follow the interactive guide. When you are done, see how to export for Claude Code, Copilot and Codex.