How to write your first Agent Skill: SKILL.md explained with a working example

One folder and one Markdown file can teach an AI coding agent a repeatable task. Here's the format, the rules that trip people up, and a skill you can copy today.

In short:

• A skill is a folder with one required file, SKILL.md.
• The description field decides when an agent uses the skill, so write it first.
• Validate the name before you share it, because some tools won't load a skill with an invalid name.

What an Agent Skill is

An Agent Skill is a folder that teaches an AI agent how to do one specific job. At minimum it holds a single SKILL.md file: YAML frontmatter on top, plain Markdown instructions below (Agent Skills specification).

The format started at Anthropic and was published as an open standard in December 2025, with tools such as Cursor, GitHub, VS Code, goose and OpenCode listed as early adopters (Simon Willison). Editors like Zed now load skills from an .agents/skills/ folder (Zed docs).

The appeal is simple. You write instructions once, and any compatible agent can pick them up when a task matches.

How agents load a skill

Skills are designed to stay out of the way until they're needed. The spec calls this progressive disclosure, and it works in three steps (spec):

1. At startup the agent reads only each skill's name and description, about 100 tokens per skill.
2. When a task matches the description, it loads the full SKILL.md body. The spec recommends keeping that under 5,000 tokens.
3. Files in scripts/, references/ or assets/ load only when the instructions point to them.

That's why the description field matters more than anything else in the file. It is the only thing the agent sees when deciding whether to use your skill.

The folder layout

changelog-writer/
├── SKILL.md
└── references/
    └── STYLE.md

Only SKILL.md is required. The scripts/, references/ and assets/ folders are optional conventions.

Where the folder goes

Each tool reads skills from its own location, so check your editor's docs. In Zed, for example, skills live in ~/.agents/skills/ for every project or in .agents/skills/ inside one project. Each skill must sit directly in that folder, with no nested groups, and project skills only load once you've marked the project as trusted (Zed docs).

The frontmatter rules that trip people up

Two fields are required (spec):

• name: 1 to 64 characters, lowercase letters, numbers and hyphens only. It can't start or end with a hyphen, can't contain --, and must match the folder name.
• description: 1 to 1,024 characters. It should say what the skill does and when to use it, with keywords an agent can match.

Optional fields include license, compatibility (up to 500 characters, only if the skill needs a specific environment), metadata and an experimental allowed-tools.

The most common mistakes are an uppercase name, a folder name that doesn't match, and a vague description like "Helps with changelogs". In Zed, for example, a skill with an invalid name fails to load and shows an error (Zed docs).

A complete example: changelog-writer

This skill turns recent commits into release notes in a consistent style.

---
name: changelog-writer
description: "Writes release notes from recent git commits in Keep a Changelog style. Use when the user asks for a changelog, release notes, or a summary of what changed since the last tag."
---

# Changelog writer

1. Find the latest tag with `git describe --tags --abbrev=0`.
2. List commits since that tag with `git log <tag>..HEAD --oneline`.
3. Group each commit under Added, Changed, Fixed or Removed.
4. Rewrite each line for users, not developers: say what changed for them.
5. Skip merge commits and dependency bumps unless they fix a security issue.

Follow the tone and formatting rules in [the style guide](references/STYLE.md).

## Example

Input commit: `fix: handle empty CSV upload without crashing`
Output line: `Fixed: uploading an empty CSV file no longer causes an error.`

The style guide sits in references/STYLE.md, so it loads only when the agent actually writes a changelog.

Keep it small

The spec gives three practical limits worth following (spec):

• Keep SKILL.md under 500 lines and move long material into reference files.
• Keep file references one level deep from SKILL.md.
• Reference files by relative path from the skill folder.

Validate before you share

The standard ships a reference library, skills-ref, that checks your frontmatter and naming:

skills-ref validate ./changelog-writer

Run it before committing a skill to a shared repo. Some agents simply skip a skill whose name breaks the rules, so it's easier to catch problems here.

Check that your agent actually uses it

A valid skill can still sit unused if its description doesn't match how people ask for the task. In Zed you can test both paths: type / and pick the skill to load it by hand, or describe the task in plain words and see whether the agent reaches for it on its own (Zed docs). If it never triggers by itself, rewrite the description before you touch the steps.

Where to go next

Start with one task your team repeats every week, such as release notes, PR descriptions or test scaffolding. Write the description first, then the steps.

Still choosing an editor to run your skills in? This Cursor vs Windsurf comparison puts both through a repository-wide refactor.

Disclosure: I work on Toolbit, which published the comparison linked above. This article was created with the help of AI and reviewed by the author for accuracy.