Agent Skills

SKILL.md

The one file every skill needs: a few fields at the top that say what the skill is, then the instructions the agent follows.


The file

  • Name it exactly SKILL.md, capitals included, and put it at the top of the skill’s folder. Codex and VS Code look for that exact name; Claude Code finds skill.md only on disks that ignore case, as macOS and Windows do by default.
  • Keep one SKILL.md per skill. OpenAI’s Skills API takes exactly one in a skill, and a SKILL.md in a subfolder makes that subfolder a skill of its own.
  • Save it as plain UTF-8 text, without the invisible byte-order mark some editors add at the start. Only Claude Code removes one.

The fields at the top

The fields, often called frontmatter, sit between a line of three hyphens at the very top of the file and the next such line. They are written in YAML, the plain key: value format:

---
name: pdf-forms
description: "Fill in PDF forms: list the fields, then fill them. Use when a PDF has fields to complete."
license: MIT
metadata:
  version: "1.2"
allowed-tools: Read Grep
---
  • Put quotes around a value that has a colon followed by a space, or that starts with a bracket or another character YAML treats specially. Without them, YAML reads the colon as the start of a new field.
  • A space followed by # ends an unquoted value, since YAML reads the rest as a comment. Quote the value to keep it.
  • Indent with spaces, never tabs; write each field once; and leave nothing after the opening three hyphens, not even a space, which uploads to the Claude apps refuse.

When the fields can’t be read, each agent fails in its own way:

AgentWhat happens
Claude CodeLoads the skill with no fields: its name falls back to the folder and it has no description to match.
Claude apps and API uploadRefuses the file, so the upload or packaging fails.
CodexCan’t read the fields and skips the skill.
VS Code and CopilotReads the fields leniently, so some values may come out differently.

The six fields

FieldRequiredWhat it holds
nameYesUp to 64 characters of lowercase letters, digits and hyphens, with no hyphen at either end and never two in a row. Make it the same as the folder’s name. Leave out the words anthropic and claude: uploading to the Claude apps refuses them.
descriptionYesUp to 1,024 characters on what the skill does and when to use it, such as “Use when a PDF has fields to complete.” Leave out < and >. The claude.ai help pages ask for 200 characters or fewer.
licenseNoThe licence: a standard name such as MIT or Apache-2.0, or the name of a licence file in the folder. Without it, readers can’t tell whether they may reuse the skill.
compatibilityNoA note of up to 500 characters on what the skill needs, such as a program or network access. Claude Code accepts it but doesn’t act on it.
metadataNoExtra facts as pairs of text, such as version: "1.2". Put numbers in quotes, or they are read as numbers rather than text.
allowed-toolsNoTools the agent may use without asking you first, in the agents that honour it, written on one line with spaces between them. Pre-approving the shell lets the skill run commands without asking.

Don’t add keys that start with github- or a local-path key under metadata: gh skill install writes them to record an install, and gh skill publish refuses the skill until they are removed.


Fields beyond the six

Agents read extra fields of their own. Claude Code reads 14 more: when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, disallowed-tools, model, effort, context, agent, background, hooks, paths and shell. VS Code reads 4: argument-hint, user-invocable, disable-model-invocation and context.

Most agents ignore fields they don’t know, but uploading to the Claude apps or the Claude API fails on any field outside the six. To use one skill everywhere, keep to the six; How agents differ lists the fields other agents add.


The instructions

Everything below the fields is the skill’s instructions, in Markdown. The agent reads them once it picks the skill.

  • Keep them under 500 lines and about 5,000 tokens. When Claude Code condenses a long conversation, it keeps only the first 5,000 tokens of a skill.
  • Move detail into reference files, and link each one from SKILL.md with a relative link such as references/forms.md. A file nothing links to is easy for the agent to miss.
  • Every link has to point to a file in the folder. Use forward slashes, and no paths that start at a drive or your home folder or climb out of the folder with ../.
  • Give a reference file of more than 100 lines a contents list near its top, so the agent can find the part it needs.
  • Leave out dates that go stale, such as “as of 2025”, and never leave the instructions empty: an empty skill loads but tells the agent nothing.

Check your file

Validate a SKILL.md reads your file the way each agent does and shows what it will reject, with the fix. Paste the file or drop the folder; it runs in your browser, and can apply the safe fixes for you.