Skip to main content
A skill is a folder. Inside the folder is a file named SKILL.md. That is the entire required format. Everything interesting about skills follows from what goes in that file and when Claude chooses to read it.
SKILL.md opens with two required fields of YAML frontmatter, and both have hard rules:
  • name: lowercase letters, numbers, and hyphens only. 64 characters max. The words “anthropic” and “claude” are reserved.
  • description: up to 1,024 characters. It must say two things: what the skill does and when to use it. This field is how Claude finds the skill, which makes it the most important sentence you will write.
Below the frontmatter comes the body: the actual instructions, in plain markdown. Workflows, formats, rules, examples. Whatever you would put in an onboarding guide for a sharp new hire who has never seen your team’s conventions.

​
The trick that makes it work

Here is the problem skills had to solve. If Claude read every installed skill into every conversation, ten thorough skills would eat the context window before you typed a word. Skills would be a tax. The solution is called progressive disclosure, and it works like a well-organized manual: table of contents first, chapters on demand, appendix only if you need it. Claude loads a skill in three levels, and each level costs nothing until it is actually reached. Run the cabinet below. Give Claude different requests and watch exactly what leaves the drawers and what it costs.
The numbers are the lesson: That last row deserves a second look. A script bundled in a skill is executed, not read. Claude runs fill_form.py and sees “23 fields filled, validation passed”, not two hundred lines of Python. Deterministic work gets done by code, and the context window pays only for the result. This is also why there is effectively no limit on how much expertise a skill can bundle: unread files cost nothing.

​
This is not a hypothetical format

The document abilities you may have already used in Claude, the ones that produce real PowerPoint and Excel files, are themselves skills. Anthropic publishes them. Here is the actual production pptx skill, open in the actual repository:
github.com/anthropics/skills · skills/pptx/SKILL.md
The real pptx SKILL.md in the anthropics/skills repository: YAML frontmatter with name and description, followed by 238 lines of instructions, with a scripts folder visible in the file tree

238 lines of markdown plus a scripts folder. This file is what stands between Claude and every slide deck it builds.

Read the description line in that screenshot. It tells Claude to use the skill any time a .pptx file is involved in any way, as input, output, or both, and then lists the situations that counts as: slide decks, pitch decks, presentations. That is a description doing its job, naming the trigger conditions explicitly. And notice the scripts/ folder in the tree: thumbnail generators, slide duplicators, validators. Code for the fragile parts, prose for the judgment calls.

​
So how is this different from a prompt snippet?

Plenty of people keep a notes file of good prompts and paste from it. That habit is the larval form of a skill. The differences are structural, not cosmetic:
A pasted snippet
  • Fires only when you remember to paste it
  • Costs its full length in every chat it enters
  • Cannot carry files, examples, or scripts
  • Lives in your notes app, invisible to your team
  • Drifts: six teammates, six versions
A skill
  • Fires itself when the request matches its description
  • Costs about 100 tokens until it is actually used
  • Bundles reference files and executable code
  • Installs once, applies in every conversation
  • Shared and versioned: update it, everyone gets the update
The mental model that survives this lesson: a prompt is something you say, a skill is something Claude knows. Saying requires you to be present and to remember. Knowing does not.

​
Say it back

Before moving on, answer these three without scrolling up:
  1. What are the only two required frontmatter fields, and which one decides whether the skill ever fires?
  2. Your skill bundles a 3,000-line reference file. What does it cost in a conversation that never touches that topic?
  3. Why does a bundled script cost fewer tokens than asking Claude to write the same code in the chat?

Format and token figures from Anthropic’s Agent Skills documentation and engineering blog. The pptx skill is source-available in anthropics/skills.