What Are Claude Skills? How They Work and How Claude Picks One
Claude skills are folders of instructions, scripts and resources that Claude loads on demand for specialised tasks. Each centres on a SKILL.md file whose description tells Claude when to use it. Claude picks a skill by its description and loads it in stages. Each skill costs context, and public GitHub issues record where picking fails.
[1] Your request
↓
[2] Claude compares it with every skill's description (about 100 tokens each)
↓
[3] Claude reads the matching SKILL.md (under 5k tokens)
↓
[4] Claude opens files or runs scripts only when the instructions call for themThe flow follows the Agent Skills overview on platform.claude.com, accessed 2026-10-21.
What are Claude skills, and what do they change?
Claude skills are folders of instructions, scripts and resources that Claude loads on demand for specialised tasks. Each centres on a SKILL.md file whose description tells Claude when to use it. They change procedure, not the model.
The Claude Help Center gives this definition:
Skills are folders of instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks.
A SKILL.md file starts with two fields, name and description, followed by Markdown instructions. Claude follows the format of Agent Skills, the open standard behind Claude skills. The same folder works in other agents that read that standard.
The Help Center lists 4 types of Claude skills:
| Type | What it is | Example or availability |
|---|---|---|
| Anthropic skills | Skills Anthropic builds and ships | PowerPoint, Excel, Word and PDF; Claude uses them automatically |
| Custom skills | Skills you write or install yourself | Any SKILL.md folder you upload |
| Organization-provisioned skills | Skills an admin turns on for everyone | Team and Enterprise plans |
| Partner skills | Skills built by partner companies | Notion, Figma and Atlassian |
A skill leaves the model unchanged. It changes which procedure and context Claude has for a task, and only when the task calls for it. Quality varies a lot between skills.
Are Claude skills just prompts?
No, Claude skills are not just prompts. A Claude skill is a saved, reusable procedure that loads only when a request matches its description. It can bundle scripts that run as code.
The platform docs state: "Unlike prompts... Skills load on demand." A skill differs from a prompt in 3 ways:
- Loads only when your request matches its description, so idle skills cost little context.
- Bundles scripts whose output enters context, while the script code itself stays out.
- Persists as a file you reuse across chats and share with a team.
Anthropic Academy draws a second contrast. Skills are automatic and task-specific. A CLAUDE.md file loads in every conversation. A slash command runs only when you type it.
How do Claude skills work and load?
Claude skills work and load by progressive disclosure. Claude keeps every skill's name and description in context from the start. It reads a skill's SKILL.md on a match, and extra files load only when called for.
Progressive disclosure means Claude loads a skill in 3 levels. The platform docs describe them this way:
| Level | What loads | When | Context cost |
|---|---|---|---|
| 1. Metadata | name and description from the front matter |
Always, at startup | About 100 tokens per skill |
| 2. Instructions | The SKILL.md body | When the skill is triggered | Under 5k tokens |
| 3. Resources and code | Reference files and scripts | Only as needed | Script output only |
The platform docs walk through a PDF skill in 4 steps:
- Start a session where Claude holds the PDF skill's name and description.
- Ask Claude to extract the text from a PDF file.
- Watch Claude read the PDF skill's SKILL.md, because the request matches its description.
- Let Claude open the form-filling reference or run a script only when the task needs one.
Claude Code keeps invoked skills longer. The content of an invoked skill enters the conversation and stays there for later turns, according to code.claude.com. The general model is explained in how every Agent Skills client loads a skill.
How much context does a Claude skill use?
An idle Claude skill costs about 100 tokens for its name and description. The rest depends on the client and the skill.
| Item | Figure | Source |
|---|---|---|
| Idle skill | About 100 tokens | platform.claude.com |
| Claude Code listing budget | 1% of the context window; each entry capped at 1,536 characters | code.claude.com, confirmed by blog.serghei.pl |
| After compaction | First 5,000 tokens of each skill's latest invocation, within 25,000 combined | code.claude.com, accessed 2026-10-19 |
The /skill-doctor command in Claude Code arrived in week 36. It shows each skill's context cost and how often you use it.
Two heavy examples sit in our library. The Claude API skill loads about 25,431 tokens of instructions at the reviewed commit 8a1541c. The file has grown since, so read our Claude API skill review for the dated figure. Skill Creator has about 8,292 tokens in SKILL.md and about 17,985 across its folder, per our Skill Creator verdict.
How does Claude decide which skill to use?
To decide, Claude matches your request against each available skill's description, which sits in its context from the start. When a description fits and the task needs help, Claude decides to use that skill automatically.
The platform docs state: "The description is what Claude matches your request against." Three rules shape the choice:
- Matching starts from the description alone, since the body stays unread until a skill is chosen.
- Thresholds apply: agents consult skills only for tasks beyond their own ability, per agentskills.io. A simple request can skip a matching skill.
- Manual control exists in Claude Code: the Skill tool,
/skill-name,disable-model-invocation: trueandpaths.
Typing /skill-name forces a skill in Claude Code. The field disable-model-invocation: true stops Claude from picking a skill on its own. The paths field limits a skill to matching files. Our hub lists Claude Code skills with verified support.
Why does the skill description matter?
The description is the only input Claude sees before it chooses a skill. A good description says what the skill does and when to use it. It is written in the third person and uses the words your users type.
Two official sources set different limits. The Help Center caps descriptions at 200 characters for claude.ai uploads. The Agent Skills spec allows 1,024 characters. Keep claude.ai uploads under 200.
The spec gives a good and a poor example:
- Good: "Extracts text and tables from PDF files... Use when working with PDF documents."
- Poor: "Helps with PDFs."
The poor version names no task and no trigger. Read the description field in the SKILL.md spec for the full rules.
When does Claude pick the wrong skill, or none?
Five of our verdicts cite trigger failures from public GitHub issues. Each is a community report, and we have not rerun those tests ourselves.
| Failure type | Skill | Evidence | Verdict | Reviewed | Update since review |
|---|---|---|---|---|---|
| Never fires | Test-Driven Development | 0 of 3 add-a-function runs invoked it on 6.4.1 (#2386, open) | Not rated here | 8ca22db | v7.0.0 on 2026-10-10 |
| Never fires | Addy Osmani's Agent Skills | Owning skill fired 0 of 6 times on inline-code requests (#620, open) | Not rated here | 2686b62 | PR #678 merged 2026-10-13 |
| Fires, writes nothing | Doc Co-Authoring verdict | 0 of 15 engaged single-turn runs wrote the file (#1718) | Conditional 67 | 8a1541c | None |
| Fires out of scope | Web App Testing | Triggers on public remote sites it is not built for (#1717) | Not rated here | 8a1541c | None |
| Wrong skill wins | Using Neon review | Parent neon skill absorbed a neon-postgres prompt in a 19-row Haiku pilot (#76) | Recommended 76 | b8250e6 | Release 2.2.0 on 2026-10-15 |
Our guide collects fixes for a skill that won't trigger.
What changed since our review?
Three projects in the table shipped changes after our review, and the Claude API skill file grew. Superpowers is the obra/superpowers project behind Test-Driven Development. It released v7.0.0 on 2026-10-10, after our review of v6.4.2, and #2386 is still open. Addy Osmani's pack merged PR #678 on 2026-10-13, which addresses part of #620. Issue #620 stays open. Neon published Release 2.2.0 on 2026-10-15, after our review of plugin 2.0.1, and #76 is still open. The Claude API SKILL.md grew from 101,724 bytes to 105,146 bytes after three commits. Issues #1718 and #1717 are open with no change. Every verdict above stays unchanged.
Where do Claude skills work: Claude apps, Claude Code or the API?
Claude skills work in the Claude apps, Claude Code and the Claude API, with the same SKILL.md format. Setup differs: the apps take ZIP uploads, the API takes workspace uploads, and Claude Code reads folders from disk.
| Claude apps | Claude API | Claude Code | Cowork | |
|---|---|---|---|---|
| How a custom skill is added | ZIP upload in Customize > Skills | Upload to /v1/skills, then skill_id in the container |
Folder on disk or a plugin | Account skills |
| Anthropic document skills | Yes | Yes | See the conflict below | Account skills |
| Who sees it | You; Team and Enterprise can share | Your workspace | You, or everyone on the repo | Your account |
| Network access | Varies by settings | None | Full | Not documented |
Two official pages disagree on sync. The platform overview says "Custom Skills do not sync across surfaces." It says pre-built document skills are not available in Claude Code. The Help Center page "Using skills in Claude" says otherwise. Claude Code v2.1.273 or later syncs account skills at session start and about every 10 minutes. Sync is one-way and skips sessions that use an API key or Bedrock. The setting is syncClaudeAiSkills. Both pages said this on 2026-10-21.
Setup steps live on two pages. One shows how to install skills in Claude Code. The other shows how to turn on and upload skills in the Claude app.
What are examples of Claude skills worth installing?
Examples of Claude skills worth installing include Anthropic's Frontend Design (76) and the Claude API skill (72). Humanizer (72) completes the top three on our Claude hub. Anthropic's PowerPoint, Excel and PDF skills score 71, 70 and 68.
| Skill | What it does | Verdict | Score |
|---|---|---|---|
| Frontend Design | Guides Claude toward distinctive web interfaces | Recommended | 76 |
| Claude API | Teaches Claude to build with the Claude API and SDKs | Recommended with caveats | 72 |
| Humanizer | Rewrites AI-sounding prose | Recommended with caveats | 72 |
| PPTX | Creates and edits PowerPoint files | Recommended with caveats | 71 |
| XLSX | Creates and edits Excel spreadsheets | Recommended with caveats | 70 |
| Reads, fills and merges PDF files | Conditional | 68 |
The first three rows are the top three on our Claude hub. The order follows verdict scores. The full order sits on the best Claude skills, ranked by verdict.
When should you use a Claude skill instead of a project, MCP or subagent?
Use a Claude skill for a repeatable procedure you keep pasting into chat. Use a project for background files and MCP for live connections to other systems. Use a subagent for separate work with its own context.
| Your need | Use | Why |
|---|---|---|
| A repeatable procedure for some tasks | Claude skill | It loads only when a task matches. |
| Background documents in one workspace | Project | Its files stay attached to every chat in it. |
| Preferences for every chat | Custom instructions or CLAUDE.md | They load in every conversation. |
| Live data or actions in other systems | MCP, often plus a skill | MCP connects tools, and the skill says how to use them. |
| A separate worker with its own context | Subagent | Claude Code context: fork runs a skill that way. |
MCP, the Model Context Protocol, connects Claude to outside tools and data. A skill tells Claude how to use them. Our comparison covers skills vs MCP in depth. For a shortlist, see which Claude skills are worth installing.
Common questions
Can I use Claude skills for free?
Yes, Claude skills work on the Free, Pro, Max, Team and Enterprise plans with code execution turned on. Our setup guide covers using skills on each Claude plan.
Can Claude create a skill for me?
Yes, ask Claude or use Skill Creator, or record one in Cowork for Mac on Pro, Max and Team. Our tutorial shows how to create a Claude skill step by step.
Can a Claude skill call another skill?
No, not explicitly. The Help Center says "skills can't explicitly reference other skills, Claude can use multiple skills together automatically."
Where is the official Claude skills documentation?
The official sources are the platform.claude.com Agent Skills overview, the code.claude.com skills page and the Help Center. Anthropic publishes The Complete Guide to Building Skills for Claude as a PDF.
Where can I find more Claude skills?
Our library lists every skill we have reviewed with its verdict and safety grade. GitHub repositories and community directories list more skills that we have not reviewed.
What does the community report about Claude skills?
Hacker News threads and GitHub issues feed our verdicts as dated evidence. Our methodology explains how we weigh trigger evidence.
Are Claude skills deterministic?
No, Claude skills are not deterministic. Choosing a skill is model behaviour, while bundled scripts give deterministic steps.
Part of the Agent Skills guide on Verify AI Skills.