What are Claude Skills?
A Claude Skill is a folder of instructions that teaches an AI assistant how to do a specific task well — write in your company's voice, build a slide deck, fill in a PDF form. At minimum it is a single file called SKILL.md; the assistant reads it only when the task at hand calls for it.
A general-purpose model knows a little about everything and the specifics of nothing — not your team's conventions, not the exact steps your workflow needs. You can paste those instructions into every conversation, or you can write them down once as a skill and let the assistant pull them in when they're relevant.
What's inside a skill
A skill is a directory. Only one file in it is mandatory:
- SKILL.md — required
- A Markdown file opening with YAML frontmatter. Only two fields are required: name (up to 64 characters, lowercase letters, numbers and hyphens, matching the folder name) and description (up to 1024 characters, covering both what the skill does and when to use it). Everything after the frontmatter is the instructions themselves.
- scripts/ — optional
- Executable code the assistant can run as part of the task. Which languages work depends on the agent running the skill.
- references/ — optional
- Longer documentation the assistant opens only when it needs the detail — a technical reference, a form template, domain notes.
- assets/ — optional
- Static files the task needs: document templates, images, lookup tables, schemas.
How a skill gets loaded
Skills are read in three stages, so an assistant can have dozens installed without carrying all of them in its head at once:
- 1 · Names and descriptions, always loaded
- At startup the assistant reads just the name and description of every installed skill — roughly 100 tokens each. That's how it knows a skill exists and when it might apply, without carrying its contents around.
- 2 · Instructions, on activation
- When your request matches a skill's description, the assistant loads that skill's full SKILL.md body. The spec recommends staying under 5,000 tokens, and keeping the file under 500 lines.
- 3 · Everything else, only if needed
- Files in scripts/, references/ and assets/ load only at the moment the task actually reaches for them — so a skill can ship a lot of material without any of it costing context up front.
Because the description is the only part the assistant sees before deciding, it is the most important line in the file. A description that says what the skill does and names the situations it applies to gets picked at the right moment; a vague one — "helps with PDFs" — leaves a perfectly good skill sitting unused.
Where skills run
Skills work in Claude Code, in Claude.ai on paid plans, and through the Claude API. The format itself is published as an open specification separate from any one product, so a skill is a portable folder rather than something locked to the app you wrote it in.
Skills or MCP servers?
The two are easy to confuse and solve opposite problems. A skill is instructions — it improves how the assistant handles something it can already reach. An MCP server is a connection — it gives the assistant access to a system it otherwise couldn't touch at all. Most real setups end up using both.
Frequently asked questions
›How do Claude Skills work?
Every installed skill contributes its name and one-line description — around 100 tokens — to what the assistant can see from the start. When your request matches one of those descriptions, the assistant opens that skill's full instructions and follows them, and reaches for the skill's bundled scripts or reference files only if the task needs them. Nothing else is loaded, so having many skills installed costs very little until one is actually used.
›Where are Claude Skills stored?
A skill is an ordinary folder on disk whose name matches the name field in its SKILL.md. Where that folder lives depends on how you added it: skills installed through the Claude Code plugin system sit alongside that plugin's files, while skills uploaded to Claude.ai or the API are held by the service rather than on your machine.
›Do you need to be a programmer to write one?
No. The required part of a skill is prose — a name, a description, and written instructions in Markdown. Programming only comes in if you choose to bundle scripts for the assistant to run, which is optional.
›How is a skill different from just writing a good prompt?
A prompt applies to the one conversation you paste it into. A skill is stored once and the assistant decides for itself when it is relevant, so the instructions arrive at the right moment in every future conversation without you remembering to include them.
›Does installing lots of skills slow the assistant down?
Only lightly. Each installed skill costs about 100 tokens of context for its name and description, and nothing more until it is activated. That design — loading detail progressively — is what makes a large library of skills practical.