SKILL.md: the file behind Agent Skills

Every Agent Skill is built around one file: SKILL.md. It is the manifest, the instructions, and the activation signal — all in one. This guide walks through the file's anatomy, from folder structure to frontmatter, and shows a minimal working example.

For the broader concepts, start with What are AI Agent Skills?. To build your own, follow the creation guide.

Folder structure

A skill is a directory. The only required file is SKILL.md; everything else is optional.

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: supporting documentation
└── assets/           # Optional: templates and resources

This layout is intentionally simple. A skill can be a single file or a small project, depending on what it needs to do.

YAML frontmatter

The top of SKILL.md is frontmatter — a small block of metadata that the agent reads during discovery. At minimum it contains a name and a description:

---
name: meeting-notes
description: Summarise meeting transcripts into structured notes. Use when the user shares a transcript or asks to summarise a meeting.
---

That frontmatter is what the agent sees before deciding to activate the skill. Everything below it loads only when the task matches.

name

The name is a short identifier for the skill. Keep it lowercase, descriptive and stable — it is how the skill is referenced and stored.

description

The description is the most important field in the file. It does two jobs at once:

1. It tells the agent when to activate the skill.
2. It tells a human what the skill does.

Good descriptions are specific about triggers and scope. A vague description ("helps with documents") rarely activates; a specific one ("Convert a markdown draft into the company's internal RFC format, including the required summary, status and review sections") activates reliably.

instructions

The body of SKILL.md is the instruction set — natural-language steps the agent follows once activated. This is where most of a skill's value lives. Write it the way you would brief a capable new colleague: assume intelligence, but not context.

Lead with the goal, then the steps, then edge cases. Keep it focused; a skill that tries to do too much becomes hard to activate and maintain.

scripts

The scripts/ directory holds executable code the agent can run — a formatter, a validator, a small CLI wrapper. Scripts extend what a skill can do beyond pure text. Because scripts execute, they deserve code-level scrutiny; see Agent Skill security.

references

references/ contains supporting documents the agent loads selectively. Instead of pasting a 30-page spec into the instructions, you reference it and let the agent pull the relevant part on demand. This keeps context lean — a key part of progressive disclosure.

assets

assets/ holds templates, images and other static resources the skill produces or consumes.

Activation and progressive disclosure

Skills load in stages:

1. Discovery — the agent reads name and description only.
2. Activation — on a matching task, the full SKILL.md enters context.
3. Execution — scripts and references load as needed.

This is why the description matters so much: it is the entire signal during discovery.

A simple example

---
name: changelog-entry
description: Draft a changelog entry from a git diff. Use when the user asks to summarise changes for a release.
---

Summarise the provided diff into a single changelog entry.

1. Group changes into Added, Changed, Fixed, Removed.
2. Write each item as one line in the imperative mood.
3. Omit internal-only or cosmetic changes.
4. Return only the entry, ready to paste into CHANGELOG.md.

That is a complete, useful skill — no scripts required.

Common mistakes

• Vague descriptions that never trigger activation.
• Overloaded scope — one skill trying to do five unrelated jobs.
• Pasting huge content into instructions instead of referencing files.
• Unclear steps that assume context the agent doesn't have.
• Ignoring edge cases the model will otherwise guess at.

Portability

Because the format is open, a well-written skill can move between compatible agents. Portability is best when a skill relies on clear instructions and standard scripts rather than one product's proprietary features.

Security implications

A SKILL.md can point at scripts that run on your machine. Before installing a skill, read the file, inspect any scripts, check shell commands and network calls, and confirm provenance. The security guide covers this in depth.

Frequently asked questions

Is SKILL.md Markdown? Yes — it is a Markdown file with a YAML frontmatter block at the top.

How long can instructions be? As long as they need to be, but focused is better. Move large material into references/.

Do I need frontmatter tools to write one? No. Any text editor works; the frontmatter is plain YAML.

Can a skill have no scripts? Absolutely. Many of the best skills are pure instructions.