How to write a SKILL.md

Frontmatter rules, third-person descriptions, folder layout, and the checklist to run before you share a Skill.

This guide summarizes the public Agent Skills specification and Anthropic’s Skill authoring best practices. Those pages are the authority if they disagree with anything here.

In this guide

The folder
Frontmatter rules
Writing the description
Writing the instructions
How specific to be
A practical checklist

Start with a folder, not a prompt dump

A Skill is a directory named after the Skill. The directory name must match the name field in SKILL.md. The only required file is SKILL.md. Everything else is optional:

my-skill-name/
├── SKILL.md          # required: YAML frontmatter + instructions
├── scripts/          # optional: code the agent can run
├── references/       # optional: docs loaded only when needed
└── assets/           # optional: templates, images, schemas

Anthropic recommends keeping the main SKILL.md under 500 lines and moving detail into those extra files. Point to each extra file from SKILL.md at the step where it is needed, using a relative path from the Skill root: references/style-guide.md, not a deep chain of files that point at other files. The spec and Anthropic both warn that nested references are easy for an agent to skim instead of fully read.

When you mention a script, say whether Claude should run it or read it. “Run scripts/analyze_form.py” and “See scripts/analyze_form.py for the algorithm” are different instructions.

Frontmatter rules

SKILL.md must start with YAML frontmatter, then Markdown. Required fields:

Field	Rules
`name`	1–64 characters. Lowercase letters, numbers, and hyphens only. Do not start or end with a hyphen, and do not use consecutive hyphens. Must match the directory name. Anthropic also forbids XML tags and the reserved words `anthropic` and `claude` in this field.
`description`	Required, non-empty, up to 1,024 characters. No XML tags. Must say what the Skill does and when to use it.

Optional fields in the open specification include:

license — a short license name or a pointer to a bundled license file.
compatibility — up to 500 characters describing environment needs (intended product, packages, network access). Most Skills should omit this.
metadata — a map of extra string keys to string values (for example author and version). Keep key names distinctive.
allowed-tools — experimental. A space-separated list of pre-approved tools. Support varies by agent.

Minimal example:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, and merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# PDF processing

## Instructions
...

You can validate a folder with the reference tooling documented on agentskills.io: skills-ref validate ./my-skill.

Write the description for discovery

Claude (and other agents that follow this design) choose a Skill by reading its description, often among many others. Anthropic’s authoring guide is specific about voice and content:

Write in the third person. Good: “Processes Excel files and generates reports.” Avoid: “I can help you process Excel files” or “You can use this to process Excel files.” Inconsistent point of view can confuse discovery because the description is merged into a system prompt.
Include what it does and when to use it, plus keywords a user would actually type: file types, product names, verbs like “review”, “extract”, or “commit message”.
Avoid placeholders such as “Helps with documents” or “Processes data.”

Anthropic also suggests consistent naming across a library. Gerund names such as processing-pdfs or noun phrases such as pdf-processing both work. Avoid helper, utils, or reserved words in the name field.

Write instructions Claude does not already know

The body has no required headings. The spec simply says to write what helps the agent do the work. In practice, the sections that work again and again are:

A one-paragraph goal.
A numbered workflow.
An output template, with the degree of strictness the task needs.
A few input/output examples.
Edge cases and explicit “do not invent X” rules.

Anthropic’s core authoring principle is that the context window is shared. Claude is already capable; a Skill should add the procedure, the constraints, and the domain facts Claude would not guess. Skip tutorials about what a PDF is. Include your field names, your review order, your forbidden claims.

Other patterns from the official best-practices doc that are worth stealing:

Progressive disclosure. Keep SKILL.md as a table of contents plus the default path. Link out to FORMS.md or reference/sales.md for the long tail.
Checklists for multi-step work, so the agent can track progress.
Feedback loops for brittle work: validate, fix, validate again, and only then proceed.
One default tool or library, with an escape hatch, instead of a menu of five equally recommended options.
Forward slashes in every path, even if you work on Windows.
No time bombs in the main path. If an API changed, document the current method and tuck the legacy note under an “old patterns” section.
Consistent terms. Pick “field” or “box”, not both.

If your Skill includes scripts, handle errors in the script instead of dumping a stack trace on the model. Justify constants. List dependencies, and remember that the Claude API sandbox cannot install packages at runtime, while claude.ai often can and Claude Code follows the machine it runs on.

Match specificity to risk

Not every Skill should read like a shell script. Anthropic describes three degrees of freedom:

High freedom — prose guidance, when several approaches are valid (a code review rubric).
Medium freedom — a preferred template with parameters (a report format you can adapt).
Low freedom — exact commands, when a wrong step is expensive (a migration, a production deploy).

Think of a narrow bridge versus an open field. Database migrations want guardrails. Brainstorming does not.

Test the Skill with the models you actually use. Instructions that feel obvious to a stronger model may be too thin for a faster, smaller one. Anthropic recommends building a few evaluation tasks before you write a long Skill, measuring the baseline without it, then adding only the instructions that close the gap.

Checklist before you share a Skill

Directory name equals name.
Description is third person, specific, and includes trigger terms.
SKILL.md is well under 500 lines, or the overflow lives in linked files one level deep.
Examples are real, not abstract.
No invented citations, dates, or credentials in the instructions themselves.
Scripts fail loudly and helpfully.
You have tried the Skill on at least three realistic prompts, including one that should not trigger it.
Someone else could audit the folder in five minutes.

When you are ready to publish, you can start from any of the free Skills in the Skillory library and replace the domain knowledge with your own.