Claude skills: what they are, how they load, and how to write one
A Claude skill is a folder with a SKILL.md file: a name, a description of when to use it, and instructions for one kind of task, plus any scripts or reference files it needs. Claude keeps only the name and description in context and loads the rest when a task matches, so you can install many skills at almost no cost. Skills work in Claude Code, the Claude API, the Agent SDK and claude.ai.
What are Claude skills?
Anthropic's docs describe Agent Skills as "modular capabilities that extend Claude's functionality". Each skill packages instructions, metadata and optional resources (scripts, templates) that Claude uses automatically when relevant. Think of a skill as the onboarding note you would hand a new teammate for one recurring job: how we write release notes, how we fill this form, how we review a migration.
The difference from a prompt is when it loads. A prompt lives in one conversation; a skill sits on the filesystem and comes in only when the task calls for it, in every conversation, without you pasting it again.
How Claude skills load: three levels
Skills use progressive disclosure: Claude reads them in stages instead of loading everything up front.
| Level | When it loads | Cost (official figures) | What it holds |
|---|---|---|---|
| 1. Metadata | Always, at startup | About 100 tokens per skill | name and description from the frontmatter |
| 2. Instructions | When the skill is triggered | Under 5k tokens | The body of SKILL.md |
| 3. Resources and code | Only when needed | Nothing until accessed | Extra markdown files, schemas, templates; scripts run and only their output enters context |
Because level 1 is so small, you can install many skills without filling the context window. The description is what Claude matches your request against, so it must say both what the skill does and when to use it. A vague description is the most common reason a skill never fires.
Scripts are the quiet win of level 3: when Claude runs validate.py, the code never enters the context, only its result does. That makes a script both cheaper and more reliable than asking Claude to write the same code each time.
Where Claude skills work
| Surface | Pre-built skills (pptx, xlsx, docx, pdf) | Custom skills | How you add them |
|---|---|---|---|
| Claude Code | No (the Claude API skill comes bundled) | Yes | Folders in ~/.claude/skills/ or .claude/skills/, or a plugin |
| Claude API | Yes | Yes | skill_id in the container parameter, with the code execution tool; upload your own through the Skills API |
| Claude Agent SDK | Yes | Loaded from .claude/ and ~/.claude/, the same way Claude Code does |
|
| claude.ai | Yes | Yes | Upload a zip in Settings, on plans with code execution enabled |
Custom skills do not sync across surfaces. On the API they are shared across the workspace; on claude.ai each user uploads their own; in Claude Code they live in your home folder, in the project or in a plugin. The runtime differs too: on the API a skill has no network access and no package installation, while in Claude Code it has the same network access as any program on your machine.
How to write a skill: the SKILL.md file
Here is a small, complete skill for a bike-rental support team (our running example in the Claude Certified Architect series):
```markdown
name: refund-summary description: Writes the internal summary for a refund request at Cogwheel Bikes. Use when an agent or a person asks to summarize a refund, prepare a refund for approval, or hand a refund case to a human.
Steps
- Read the booking: bike, dates, amount paid, deposit state.
- State the customer's request in one sentence, in their words.
- List what the tools confirmed, and what they could not check.
- If the amount is over $100, end with "Needs human approval".
Format
Five lines at most. Booking ID first. ```
The rules on the API side are strict: name is at most 64 characters, lowercase letters, numbers and hyphens only, and may not contain the words "anthropic" or "claude"; description is required and at most 1,024 characters. In Claude Code every field is optional (the name defaults to the folder name), but a description is strongly recommended, and the listing truncates description plus when_to_use at 1,536 characters.
Claude Code skills and slash commands
In Claude Code, custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy, and old command files keep working. Skills add a folder for supporting files and frontmatter that decides who may invoke them.
| Level | Path | Wins a name conflict over |
|---|---|---|
| Enterprise | .claude/skills/<name>/SKILL.md in the managed settings directory |
personal and project |
| Personal | ~/.claude/skills/<name>/SKILL.md |
project |
| Project | .claude/skills/<name>/SKILL.md |
|
| Plugin | <plugin>/skills/<name>/SKILL.md, called as /plugin-name:skill-name |
namespaced, no conflict |
Arguments come in through placeholders: $ARGUMENTS for everything you typed after the command, $0, $1 and so on for positions, or named arguments declared in the frontmatter. A line such as !`git diff HEAD` runs a command and inlines its output before Claude reads the skill.
Skill frontmatter options worth knowing
disable-model-invocation: true: only you can trigger it, by typing its name. Good for anything with side effects, like a deploy.user-invocable: false: only Claude can load it; it stays out of the/menu.allowed-tools: tools Claude may use without asking permission while the skill runs. It pre-approves; it does not restrict. To remove tools, usedisallowed-tools.context: fork(withagent): run the skill in a forked subagent, so its long output stays out of your main conversation.argument-hint: the hint shown in autocomplete, such as[booking-id].paths: glob patterns that limit when the skill activates.modelandeffort: run the skill on a different model or effort level.
Skills vs CLAUDE.md vs subagents vs MCP
| Loads | Best for | |
|---|---|---|
| CLAUDE.md | Every session, always | Standards for everything: build commands, conventions |
| Skill | On demand, when it matches or is called | One recurring workflow with its own steps and files |
| Subagent | When delegated, in its own context | A focused job whose details should not flood your context |
| MCP server | When connected, its tools are listed | Access to outside systems and data |
They combine well: a skill can run in a forked subagent, and its steps can call MCP tools. For how the API, the Agent SDK, Claude Code and MCP fit together, see Claude Agent SDK vs Claude Code vs the API vs MCP.
Claude skills on the Claude Certified Architect exam
Task statement 3.2 of the CCAR-F guide covers skills directly: skills in .claude/skills/ with SKILL.md frontmatter, context: fork to keep verbose output out of the main conversation, allowed-tools and argument-hint, personal variants in ~/.claude/skills/, and choosing a skill (on-demand, task-specific) over CLAUDE.md (always loaded, universal).
One difference from today's docs: the guide's example treats allowed-tools as a way to restrict tools during a skill. Current Claude Code docs say it pre-approves tools, and disallowed-tools is the field that removes them. On the exam, follow the guide's framing; in your own projects, use the docs.
Use skills from trusted sources only
A skill can carry instructions and code, so a malicious one can direct Claude to call tools or run code that has nothing to do with its stated purpose. The docs' advice: use skills you wrote or got from Anthropic, audit every file of anything else (SKILL.md, scripts, resources), and be wary of skills that fetch content from outside URLs.
More on the exam in the CCAR-F study plan, and every topic in all articles.
Sources: Agent Skills overview; Skills in Claude Code; Claude Agent SDK overview; Claude Code memory and CLAUDE.md; Claude Certified Architect Foundations exam guide v1.0, task statement 3.2.
FAQ
What is a Claude skill?
A directory with a SKILL.md file whose YAML frontmatter gives a name and a description, followed by instructions. It can bundle extra markdown files, scripts and templates. Claude loads it automatically when a request matches the description, or when you call it by name.
Where do I put skills in Claude Code?
Personal skills go in ~/.claude/skills/<skill-name>/SKILL.md and project skills in .claude/skills/<skill-name>/SKILL.md. Plugins can ship skills too, invoked as /plugin-name:skill-name.
Are skills the same as slash commands?
In Claude Code, custom commands have been merged into skills. A file in .claude/commands/deploy.md and a skill in .claude/skills/deploy/SKILL.md both create /deploy. Skills add a folder for supporting files and frontmatter that controls who can invoke them.
What is the difference between a skill and CLAUDE.md?
CLAUDE.md is read at the start of every session, so it holds standards that apply to everything. A skill loads only when it is needed, so it holds task-specific workflows.
Do skills sync between claude.ai, the API and Claude Code?
No. Custom skills are managed per surface: upload them to claude.ai and to the API separately, while Claude Code reads them from the filesystem.