SKILL.md

Why you'd careThe problem it solves

You have a forty-line preamble you paste at the top of every session. How migrations work here. Which columns are soft-deleted. Why the staging seed script has to run before the test suite. You paste it, the session ends, you paste it again. Sometimes you forget a paragraph and the model does the wrong thing, and afterwards you cannot tell whether the model was wrong or the paragraph was missing. A skill is the packaging answer to that: the preamble becomes a directory on disk, the harness finds it without being told, and it loads when the work actually calls for it instead of at the top of every conversation. The first thing to get right is the shape of that directory, because the loader is unforgiving about exactly one part of it — and it is not the part most people guard.

ConceptWhat it is

A skill is a directory. The only member the loader requires is a file called SKILL.md at its root. That file opens with a YAML block fenced by --- lines; everything after the closing fence is Markdown that the model reads as procedural instruction, not as a document to summarize.

The split matters more than it looks. The frontmatter is metadata about the skill — what it is, when to reach for it — and it is what tooling parses. The body is addressed to the model that will do the work. Anthropic's own authoring guidance is blunt that you are writing for another instance of Claude rather than for a human reader, which is why its house style for the body is imperative and verb-first rather than explanatory.

Two names are in play and they are easy to conflate. The directory name is what the harness scans for and what the packaging script uses to name its output file. The name: key inside the frontmatter is a separate required string with its own format rules. Nothing forces the two to agree. Anthropic's skill-creator explicitly instructs that both the directory name and the name field be carried through unchanged when revising a skill, which is a strong hint that you should make them match once and then never touch either again.

Everything else is optional and conventional. scripts/, references/, assets/ are habits, not requirements. A directory containing nothing but a SKILL.md is a complete, valid, working skill.

How it worksThe mechanics

Discovery is a filesystem scan. Claude Code walks its skill locations and a subdirectory counts as a skill if and only if it contains SKILL.md. The check is for that literal file name; skill.md or Skill.md gets walked straight past on a case-sensitive volume, and this is the failure that produces the maddening symptom of a skill that exists on disk and does not appear in the session at all.

my-skill/
├── SKILL.md          <- required, this exact name
├── scripts/          <- executable code
├── references/       <- docs read into context on demand
└── assets/           <- files copied into your output

The file itself is unremarkable:

---
name: my-skill
description: This skill should be used when the user asks to ...
---

# My Skill

To do the thing, first ...

Parsing is strict at the front and loose everywhere else. Anthropic's quick_validate.py requires the file to start with --- and extracts the block with the pattern ^---\n(.*?)\n---. A blank line, a byte-order mark, or a comment before the opening fence produces “No YAML frontmatter found”. The block must then parse as a YAML dictionary, and it must contain name and description. Those two keys are required by the spec, the validator and every upload path — but not by Claude Code itself, which reads frontmatter only when the opening --- is the first line, treats a file without it as all body, and defaults name to the directory name and description to the first non-empty body line.

After the closing fence, nothing is enforced at all. There is no mandatory heading, no schema, no section the loader looks for, no length the loader rejects. The body is text, and when the skill fires it is loaded verbatim into the model's context. That asymmetry — rigid header, entirely free body — is the whole design. The header is for machines deciding whether to load; the body is for a model deciding what to do.

At a glanceSee it

How the harness turns a directory on disk into a loadable skill, and the two points where it gives up.

Where it runsSurfaces and availability

The pattern to read here is stronger than it looked: the SKILL.md folder is now the authoring format across three vendors, not just Anthropic's — Claude Code, Codex and Antigravity all scan directories for a SKILL.md, and two of the three have converged on the same .agents/skills path. Only local harnesses consume the folder directly; every hosted Anthropic surface wants an uploaded object with an ID, which is why you should draft on disk, where the edit-test loop is a file save, and register the skill only once its behaviour has stopped changing. The one place with genuinely nothing to port to is Amazon Bedrock and Vertex AI, where Agent Skills are explicitly absent from the feature list. That is a statement about those two products, not about AWS or Google as such: Claude Platform on AWS supports Skills, and Antigravity has its own.

ExampleIn the real world

Your team's release notes always come out wrong in the same three ways: the wrong date format, the internal ticket IDs left in, and the breaking-change section omitted when there are no breaking changes instead of being marked “None”. You create ~/.claude/skills/release-notes/ and put one file in it.

The frontmatter says name: release-notes and a description that names the trigger phrases people actually use — “draft the release notes”, “write the changelog entry”, “prep the 4.2 announcement”. The body is about six hundred words: the section order, the ISO date rule, the instruction to strip anything matching the ticket prefix, and the rule that the breaking-changes heading is always present and reads “None” when empty.

Next session, you type “draft the release notes for 4.2”. You do not name the skill. The model has been holding only the one-line description in context; it matches, reads the body, then reads your git log. What comes back has the ISO dates, no ticket IDs, and a breaking-changes heading that says None. You did not paste anything. When the date rule changes next quarter, you edit one file and every future session inherits it.

Not thisWhat it is often confused with

• Not a config filethe frontmatter is configuration, but the body is instruction the model acts on. Nothing parses the body into settings; it is read the way a briefing document is read.
• Not a prompt templatethere are no slots, no variable substitution, no render step. The text you write is the text the model sees, unchanged.
• Not a toola tool has an input schema and returns a value to the model. A skill has neither. The model reads a skill; it calls a tool. A skill can tell the model which tools to call.
• Not a plugina plugin is a distribution container that may hold several skills alongside commands, agents, hooks and MCP server definitions. Skills live inside plugins; plugins are not a kind of skill.
• Not CLAUDE.md or AGENTS.mdthose are always-on project memory, loaded whether or not they are relevant. A skill's body is loaded conditionally, which is the entire point of packaging it as one.

LimitsWhen not to reach for it

• The instruction is one-off.If you will say it once, say it. A skill is a fixed authoring cost that pays back over repetitions, and a skill written for a single task is slower than typing the sentence.
• The content changes per query.Skills are static files. If the right answer depends on today's database rows or this week's ticket queue, you want retrieval or a tool call, not a folder that has to be edited to stay true.
• The model needs to act on a live system.A skill can describe an API perfectly and still not be able to reach it. Reaching for an MCP server or a tool definition is the correct move.
• It genuinely must apply on every turn.Coding standards that are never optional belong in the system prompt or in CLAUDE.md. A skill that must always fire is a skill whose conditional loading is pure overhead.
• Your team's tools do not read the format.Cursor, GitHub Copilot and dozens of other clients now load SKILL.md folders, but in a client that does not implement Agent Skills the folder is a file nobody's tooling reads. Check the client first; where it falls short, AGENTS.md or the IDE's own rules format will actually load.

RelatedGo deeper