What Are Claude Skills? A Plain-English Guide for Developers and Teams
A skill is a folder of instructions that Claude loads only when a task needs it. Here's how that works, how skills differ from prompts, Projects and MCP, and when it's worth writing one.
If you’ve used Claude for a while, you’ve probably got a few blocks of text you paste in again and again. The house style for release notes. The checklist for reviewing a pull request. The six steps for turning a sales call transcript into a CRM update. A skill is where that text goes so you can stop pasting it.
That’s the short version. The rest of this post covers what a skill actually is on disk, why it doesn’t slow Claude down, how it differs from the other ways of giving Claude context, and when it’s worth writing one.
A skill is a folder
Anthropic’s Help Center describes skills as “folders of instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks.” The only file a skill must have is SKILL.md. Everything else is optional.
release-notes/
├── SKILL.md # required: name, description, instructions
├── template.md # optional: a file Claude reads when it needs it
└── scripts/
└── changelog.py # optional: code Claude runs instead of retyping it
SKILL.md has two parts. At the top, between --- lines, is a little YAML block with a name and a description. Below that is ordinary Markdown: the instructions you’d give a new colleague.
---
name: release-notes
description: Write customer-facing release notes from a list of merged PRs, in our house style. Use when the user asks for release notes, a changelog entry, or a "what's new" post.
---
# Release notes
1. Group changes under New, Improved and Fixed. Skip internal refactors.
2. One line per change, written for customers, not engineers.
3. Use template.md for the layout.
That’s a complete, working skill. There’s no build step and no code required, though you can bundle scripts when you want something done the same way every time.
The format has a few rules. Under the Agent Skills specification, name is up to 64 characters of lowercase letters, numbers and hyphens, and must match the folder name. Claude’s own docs add that it can’t contain the words “anthropic” or “claude”. The description can run to 1,024 characters, and it has a job to do, which brings us to how skills load.
Why installing twenty skills doesn’t cost you twenty skills’ worth of context
Claude doesn’t read every skill up front. Anthropic calls the approach progressive disclosure, and it works in three stages:
| Stage | What Claude has in context | Rough cost, per Anthropic’s docs |
|---|---|---|
| At startup | Each skill’s name and description |
About 100 tokens per skill |
| When a request matches | The body of that skill’s SKILL.md |
Under 5k tokens |
| Only if the instructions call for it | Extra files it reads, or the output of scripts it runs | Nothing until used |
So the description is doing the matchmaking. Claude compares your request against it to decide whether to open the skill at all. That’s why the docs keep insisting the description say both what the skill does and when to use it. “Helps with release notes” is too thin. “Write customer-facing release notes from merged PRs. Use when the user asks for release notes or a changelog” gives Claude the words people actually type.
Scripts are the other clever part. When a skill tells Claude to run changelog.py, the code itself never enters the conversation. Only the output does.
Skills vs prompts, Projects, custom instructions and MCP
Claude has several places to put context, and they overlap enough to be confusing. Here’s how Anthropic draws the lines:
| What it’s for | When it’s loaded | |
|---|---|---|
| A prompt | A one-off instruction in one conversation | Only in that chat |
| Custom instructions | Preferences that apply to everything you do | Every conversation |
| A Project | Background documents for one body of work | Every chat inside that Project |
| A skill | A procedure for one kind of task | Only when a task matches its description |
| An MCP server | A connection to an outside tool or data source | While the connection is switched on |
The one people mix up most is MCP. The Help Center puts it neatly: MCP connects Claude to external services and data, while skills provide procedural knowledge. They aren’t rivals. An MCP connector can give Claude access to your issue tracker, and a skill can tell it how your team writes a ticket: which labels, which template, who to assign. You’ll often want both.
In Claude Code there’s one more: CLAUDE.md. The Claude Code docs suggest moving something into a skill once a section of CLAUDE.md “has grown into a procedure rather than a fact”. The reason is the same as above. CLAUDE.md is always loaded; a skill’s body only loads when it’s used.
Where skills work
Skills work in all of Claude’s main products, but each one handles them a little differently.
- Claude Code. Skills are plain folders. Put them in
~/.claude/skills/to have them in every project, or in a repository’s.claude/skills/so everyone who clones it gets them. You can also run one directly by typing/and its name. Old custom commands in.claude/commands/still work; they’ve been merged into skills. - Claude apps. You upload a skill as a ZIP. It needs code execution turned on. On Team and Enterprise plans, the Help Center says organization Owners can now provision skills for every member.
- Claude API. Skills run through the code execution tool. Custom skills uploaded through the Skills API are shared across the workspace.
One thing that catches people out: custom skills don’t sync between these surfaces on their own. Anthropic’s docs are explicit that a skill uploaded to the Claude apps isn’t automatically available in the API, and that Claude Code’s file-based skills are separate from both. (Claude Code can download the skills enabled on your Claude account when you sign in with it, but that’s a one-way download.)
Anthropic also ships ready-made skills for Word, Excel, PowerPoint and PDF files. Those are the ones working in the background when Claude makes you a spreadsheet.
It’s not just a Claude thing
Anthropic first developed the format and then published it as an open standard at agentskills.io. The site lists a long run of tools that support it, including Cursor, OpenAI’s Codex, GitHub Copilot, VS Code and Gemini CLI. In practice that means a well-written SKILL.md can travel. Some tools add their own extra frontmatter fields, so if you want one file that works everywhere, stick to the six fields in the spec: name, description, license, compatibility, metadata and allowed-tools.
When is a skill worth writing?
The Claude Code docs give the clearest test: write a skill when you keep pasting the same instructions, checklist or multi-step procedure into chat. A few other good signs:
- The task has a right way to do it. Your brand voice, your report format, your review checklist.
- More than one person does it. A skill in the repo means the whole team gets the same procedure, and changes to it go through code review like anything else.
- Part of it should be exact. Date math, file conversions, validation. Put that in a script and let Claude run it.
And when not to bother: if it’s a one-off request, just ask. If it’s a preference that applies to everything, like “use British spelling”, custom instructions or CLAUDE.md are the better home.
Before you install someone else’s skill
A skill can carry scripts, and in Claude Code its allowed-tools field can pre-approve tools for the turn it runs in. Anthropic’s advice is blunt: use skills from sources you trust, and read every file in one before you use it. Watch for scripts that make network calls, read files they have no reason to touch, or do things the description doesn’t mention. Treat it the way you’d treat installing any other software.
It’s also why each skill page on Skillaisle lists what’s in the pack and how it was tested, so you can check before you download.
Try one
The quickest way to get it is to install a skill and watch Claude pick it up. Our guide to installing skills in Claude Code and the Claude apps walks through both, and the skills aisle has free skills you can open up and read first.
Sources
- Claude docs: Agent Skills overview
- Claude Help Center: What are skills?
- Claude Code docs: Extend Claude with skills
- Agent Skills: Overview
- Agent Skills: Specification
Products change quickly. If something here no longer matches what you see, the official page above is the reference.
Related on Skillaisle
Want the setup steps? Browse the Learn guides or walk the skills aisle.