Guides · Updated
What Are Claude Skills?
Claude skills are folders of instructions that Claude loads only when a task calls for them. What is inside one, how Claude decides to use it, and where skills work.
A Claude skill is a folder containing a file called SKILL.md, which holds written instructions for one kind of task. Claude reads the short description of every skill you have installed, and when your request matches one, it loads that skill's full instructions and follows them. Skills are how you teach Claude a procedure once instead of pasting it into every conversation.
Anthropic also calls them Agent Skills. The format was developed by Anthropic and then released as an open standard at agentskills.io, so the same folders work in other agents as well.
What is inside a skill
The only required file is SKILL.md. It has two parts: a block of YAML frontmatter at the top, and Markdown instructions below it.
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files.
---
# PDF processing
Step-by-step instructions for the agent go here.
The standard requires two frontmatter fields:
nameidentifies the skill. It uses lowercase letters, numbers and hyphens, up to 64 characters, and matches the folder name.descriptionsays what the skill does and when to use it, in up to 1,024 characters. This is the text Claude matches your request against.
A skill folder can also hold other files. The specification suggests three optional directories: scripts/ for code the agent can run, references/ for extra documentation, and assets/ for templates and other static files.
my-skill/
├── SKILL.md # required: metadata and instructions
├── scripts/ # optional: executable code
├── references/ # optional: documentation
└── assets/ # optional: templates, resources
How Claude decides to use one
Skills load in three stages, which the documentation calls progressive disclosure.
- Discovery. When a session starts, Claude loads only the name and description of each available skill. The specification puts this at roughly 100 tokens per skill.
- Activation. When a task matches a description, Claude reads the full
SKILL.mdinto context. - Execution. Claude follows the instructions, and opens bundled files or runs bundled scripts only if the task needs them.
This is why you can keep many skills installed. A skill costs almost nothing until it is used. When a script runs, only its output enters the conversation, not its source code.
It also explains the most common problem. If Claude does not use a skill when you expect it to, the description usually does not contain the words you used in your request.
In Claude Code you do not have to wait for Claude to choose. Every skill is also a command, so typing /skill-name runs it directly.
What skills are used for
Anthropic's documentation describes skills as a way to package workflows, context and best practices so you do not repeat the same guidance in every conversation. In practice they fall into two groups.
Reference skills add knowledge Claude applies to whatever you are doing: your API conventions, a style guide, how a legacy system works.
Task skills are step-by-step procedures you run on purpose: deploy the app, write a commit, review a pull request, produce a report.
Anthropic ships four pre-built skills for documents, covering PowerPoint, Excel, Word and PDF files, which Claude uses on claude.ai when you ask it to create those files. Claude Code includes its own bundled skills, such as /code-review and /debug. Everything else is written by users and published in repositories, which is what this directory collects. See Claude skills examples for real ones.
Where skills work
Skills are available across Claude's products, with some differences.
| Product | How skills get there |
|---|---|
| Claude Code | Folders in ~/.claude/skills/ (all your projects) or .claude/skills/ (one project), or inside a plugin |
| claude.ai | Pre-built document skills are on by default; custom skills are uploaded as a zip file in Settings > Features |
| Claude API | Pre-built skills by ID, or custom skills uploaded through the Skills API; requires the code execution tool |
On claude.ai, custom skills are available on Pro, Max, Team and Enterprise plans with code execution enabled, and each user uploads their own. The pre-built document skills are not available in Claude Code.
Outside Claude, the agentskills.io site lists many agent products that support the format. That is why the same skill can often be installed in Claude Code, Codex and Cursor from one repository.
Skills compared with the alternatives
A few neighbouring features are easy to confuse with skills.
- CLAUDE.md is a file of project facts that is always loaded. A skill's body loads only when used, so a long procedure belongs in a skill and a short fact belongs in CLAUDE.md.
- MCP servers connect Claude to outside tools and data. A skill tells Claude how to do something; an MCP server gives it access to something. See Claude skills vs MCP.
- Plugins are bundles that can contain several skills along with subagents, hooks and MCP servers. See Claude skills vs agents, plugins and commands.
- Custom slash commands in Claude Code have been merged into skills. Old command files still work.
What to watch for
A skill is instructions plus, sometimes, code. Anthropic's guidance is to use skills only from trusted sources, meaning ones you wrote or got from Anthropic, and to audit anything else before use: read SKILL.md, read the scripts, and look for network calls or file access that do not fit the stated purpose.
Skills also behave differently by product. On the API, skills run in a sandboxed container with no network access. In Claude Code they run on your machine with the permissions you have given Claude Code.
Where to go next
- To install one, read how to use Claude skills.
- To write one, read how to create a Claude skill.
- To see what people have published, browse the directory or the best Claude skills list.
Questions people ask
Are Claude skills free?
The format is an open standard, and most published skills are free and open source. Custom skills on claude.ai need a paid plan with code execution enabled. A skill's instructions count toward your usage like any other text Claude reads.
Do Claude skills only work with Claude?
No. The format is published as the Agent Skills open standard, and other agents read the same SKILL.md folders, including Codex, Cursor, OpenCode, Gemini CLI, GitHub Copilot and OpenClaw. A skill that relies on a feature only Claude Code has may not behave the same elsewhere.
Is a skill the same as a prompt?
A skill is a prompt that is stored in a file, has a name and description, and loads only when it is needed. It can also bring scripts and reference files with it, which a pasted prompt cannot.
Do skills use up the context window?
Only a little until they are used. The name and description of each skill are loaded at startup. The full instructions are loaded when the skill is activated, and bundled files are read only if the task needs them.
Are skills safe to install?
A skill can tell the agent to run commands and can include scripts, so treat it like code. Install skills from sources you trust and read the SKILL.md and any scripts first.