Agent Skills and SKILL.md: How the Format Works and How to Write One

A skill is a directory containing a SKILL.md file with a name, a description and a Markdown body. Agents read only the name and description at startup, and load the body and any supporting files when a task matches. As of October 2026 the format is published as an open specification at agentskills.io, and the MCP specification lists "Skills over MCP" as an extension for discovering skills through MCP. A good skill has a precise description, a short body and reference files for detail.

The spec asks for very little: one file, two fields. According to the Agent Skills specification, a skill is a directory that contains at minimum a SKILL.md with YAML frontmatter followed by Markdown instructions. Optional scripts/, references/ and assets/ directories hold executable code, documentation and static resources.

The constraints on the frontmatter, as the specification states them:

A minimal skill looks like this:

---
name: migration-review
description: Reviews database migration files for locking risk, missing rollbacks and data loss. Use when the user asks to review, write or check a SQL migration.
---

# Migration review

1. Read the migration and any referenced schema files.
2. List every statement that takes a table lock on a large table.
3. Check that a rollback exists and that it is tested.
4. Report findings ordered by severity, each with the statement and a fix.

That is a complete skill. Everything else in the format exists to keep it from consuming context it does not need.

Progressive disclosure means the agent pays for detail only when a task needs it. The specification describes three levels: roughly 100 tokens of metadata for every installed skill loaded at startup, the full SKILL.md body (under 5,000 tokens recommended) when the skill activates, and files from scripts/, references/ or assets/ only when required.

This matters because context is a limited resource. Anthropic's engineering team describes context as a finite "attention budget" and recommends aiming for the smallest set of high-signal tokens in its post on effective context engineering for AI agents. A hundred skills that each cost 100 tokens at startup is a manageable overhead. A hundred skills that each load 5,000 tokens up front would not be.

If you want the wider picture of how skills fit alongside instructions files, hooks and subagents, see Agent skills and harnesses: a practitioner guide and the Agent Stack overview.

The description is the only part of your skill the agent sees when deciding whether to use it, so most failures trace back to it. The spec's own contrast is useful: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction. is a good description, and Helps with PDFs. is a poor one.

Three habits help. State the action and the object ("reviews migration files"). Add a "use when" clause with the phrases a person would actually type. And say what the skill does not cover, if a neighbouring skill could be confused with it.

The body is the procedure. Write it as numbered steps with a clear output, because the agent will follow it literally. The specification recommends step-by-step instructions, examples of inputs and outputs, and common edge cases.

Put these in the body:

• The sequence of steps and the exact output format you want back.
• One or two short worked examples.
• Hard rules, such as "never run DROP statements; report them instead."

Move these into references/ or scripts/:

• Long tables, style guides and API listings that only some tasks need.
• Deterministic work. If a check can be a script that returns a pass or fail, a script is cheaper and more reliable than asking the model to do it in prose.

The spec also advises keeping file references one level deep from SKILL.md and avoiding long reference chains, which keeps the agent from chasing links through several files.

A skill is text that changes what an agent does, and some skills include scripts that run on your machine. Treat third-party skills the way you treat dependencies: read them before installing, and prefer ones whose scripts you can inspect. The allowed-tools field lets a skill declare tools that are pre-approved to run, but the spec marks it experimental, so check how your agent handles it before relying on it for safety. Your approval rules should still decide what runs without a human, which is the subject of When Should an AI Agent Ask Permission?.

For the same reason, validate your own skills. The specification points to the skills-ref reference library, which checks that frontmatter follows the naming rules, for example skills-ref validate ./my-skill.

A skill can make results worse. It can bloat context, steer the agent toward an outdated process, or trigger when it should not. The only way to know is to compare runs. Pick five to ten representative tasks, run them without the skill, run them with it, and compare outcomes and cost. The measure-agent-skills lab walks through a baseline-versus-skill experiment, and Build an eval pipeline covers the wider harness.

1. Pick the instruction you paste most often and turn it into a skill with a specific description. 2. Keep the body under a page. Move anything optional into references/. 3. Run five tasks with and without the skill, and keep it only if results improve. 4. Review any skill you did not write before installing it.

What is a SKILL.md file? It is the one required file in an Agent Skills directory. It has YAML frontmatter with a name and description, followed by Markdown instructions the agent follows once it activates the skill.

How is a skill different from a prompt or a system instruction file? A prompt or always-loaded instructions file consumes context on every request. A skill loads only its name and description until a task matches, then loads the body, so you can install many without paying for all of them each time.

How long should a skill be? The specification recommends keeping SKILL.md under 500 lines and the activated instructions under about 5,000 tokens. Move detail into reference files that load on demand.

Do skills work across different AI tools? The format is an open specification, and several tools read it. Support for individual fields, especially the experimental allowed-tools, varies, and we could not verify a current compatibility matrix, so test your skill in each tool you use.

Why is my skill never triggered? Usually the description is too vague or lacks the phrases people actually use. Rewrite it with the action, the object and a "use when" clause, then test with realistic requests.

Can a skill run code? A skill can include scripts in a scripts/ directory, with supported languages depending on the agent. Because scripts execute on your machine, review them and keep your approval rules in place.

What is Skills over MCP? The MCP specification lists it as an optional extension for discovering and consuming skills through MCP. It is a community working-group effort, so check the current MCP documentation before building on it.