Part IV · Applied concepts · Chapter 31

Skills

A skill is a folder of instructions, and optionally scripts and reference files, that an agent loads only when a task needs it. Skills let you teach an agent a procedure once, such as "how we add an environment variable here", without paying for those instructions in every conversation. This chapter explains how they work, how to write one, and walks through an example skill you can run.

Why it matters

An agent that works in a codebase needs the team's habits: which files change together, which checks to run, what never to touch. Writing them into every prompt wastes context; leaving them out produces work that ignores them. Skills are the middle path, loaded on demand.

What a skill is

A skill is a directory with a file called SKILL.md. The file starts with YAML frontmatter holding two required fields, then a Markdown body with the instructions:

keeping-env-docs-in-step/ SKILL.md frontmatter (name, description) + the steps scripts/check_env_docs.py a deterministic check the steps tell the agent to run

name: at most 64 characters, lowercase letters, digits and hyphens only, and it must not contain the reserved words "anthropic" or "claude". Names in the gerund form, such as processing-pdfs, are recommended.
description: at most 1,024 characters, saying both what the skill does and when to use it, written in the third person, because it is inserted into the agent's system prompt.

Skills were introduced for Claude and published as an open standard in December 2025. The details in this chapter come from Anthropic's documentation.

Progressive disclosure

A skill is loaded in three levels, each only when needed:

Level	What	When it enters the context	Typical cost
1	The name and description	Always, at start-up	About 100 tokens per skill
2	The body of `SKILL.md`	When the agent decides the skill applies	Under 5,000 tokens
3	Bundled files and scripts	Only when the instructions point to them	Nothing until read; a script's output, not its source, enters the context

Worked: an agent with 40 skills installed pays about 40 × 100 = 4,000 tokens for their descriptions in every conversation. If the instructions were pasted into the system prompt instead, at up to 5,000 tokens each, the same 40 would cost up to 200,000 tokens, more than many context windows. A task that triggers two skills adds about 10,000 tokens, and only for that task.

The description is doing the selecting, so it decides whether the skill is ever used. A vague one ("helps with config") is skipped or fires at the wrong time; a specific one names the trigger ("Use when a change introduces, renames or drops an environment variable").

Where skills run

Surface	How skills get there	Notes
Claude API	Uploaded through the Skills API, then listed in a request's container, with the code execution tool enabled	Up to 20 skills per request; the container has no network access
Claude Code	Folders in `~/.claude/skills/` (personal) or `.claude/skills/` (project), or from a plugin	A skill also becomes a slash command; scripts can use the network
claude.ai	Uploaded as a zip in the settings, on plans with code execution	Per user, not shared across an organisation
Claude Agent SDK	Folders on disk, found through the setting sources	An explicit tool list must include "Skill"

Custom skills do not sync between these surfaces: each one is installed separately.

Writing a good skill

Only what the agent lacks. The context window is shared, and the agent is already capable. Skip general knowledge; write the local facts and the order of steps.
Short body, linked detail. Keep SKILL.md under 500 lines and move detail into files it links to directly (one level deep). Give a long reference file a table of contents.
Scripts for anything exact. A comparison, a format check or a calculation belongs in a script the agent runs, which gives the same answer every time and handles its own errors.
Evaluate it. Write at least three realistic tasks before polishing the text, and check the skill fires on them, does not fire on near misses, and helps on every model you will use.
Paths with forward slashes, and full names for tools from MCP servers (ServerName:tool_name).

Trust

A skill is instructions plus code that an agent will follow and run with its own permissions. Install skills only from sources you trust: ones you wrote or ones from the vendor. Before using any other, read every file it bundles, looking for unexpected network calls, file access, or instructions to fetch content from outside URLs. A skill that says it formats tables and also asks the agent to upload a file is exactly what to look for.

Skills, tools, MCP and subagents

Note the audience. A skill guides an agent that works on your code, such as a coding agent in a repository. It is not part of the running application, whose own tools and prompts serve its users.

Mechanism	What it gives the agent	Use it for
Tool	A function it can call	An action or a lookup (chapter 28)
MCP server	A packaged set of tools, resources and prompts behind a protocol	Connecting a service to many applications (chapter 30)
Skill	Instructions and scripts, loaded on demand	A procedure, house rules, a workflow
Subagent	A separate agent with its own context	Delegating a self-contained task (chapter 32)
System prompt	Text present in every call	Rules that apply to everything

Example: keeping environment-variable docs in step

Many projects list every environment variable twice: in .env.example (the name with a blank or default value) and in a README table under "Environment variables", in the same group. Adding a variable to the code and forgetting one of the lists is an easy mistake. The folder labs/skill-example/keeping-env-docs-in-step/ holds a skill for exactly this job, and labs/skill-example/demo/ holds an invented recipe-site project to run it against: in-step passes, and drifted has two deliberate mistakes.

The frontmatter. The description says what (adds, renames or removes a variable and keeps the two lists in step with the code) and when (a change introduces, renames or drops a variable, or the lists disagree).
The rules. Never open .env; a secret gets a blank value and "yes" in the README's Secret column; the same group in both files.
The steps. Find every place the variable is read; edit .env.example; add the README row in the table's own column order; run the checker; show the user the two changes and the checker's output.
The script. The skill's own scripts/check_env_docs.py, inside that folder (standard library only), collects the names in .env.example and in the README's environment tables, prints each name found in only one of them, and exits with 1 if there is any. It reads names only and never prints anything after an "=", so a real value pasted into the example file by mistake cannot leak through its output.

Run from the repository root against the two demo projects, it printed the following (the second run exited with status 1):

python labs/skill-example/keeping-env-docs-in-step/scripts/check_env_docs.py --repo labs/skill-example/demo/in-step .env.example: 6 names; README tables: 6 names in step python labs/skill-example/keeping-env-docs-in-step/scripts/check_env_docs.py --repo labs/skill-example/demo/drifted .env.example: 6 names; README tables: 6 names only in .env.example: DATABASE_POOL_SIZE only in README: CACHE_TTL_SECONDS

The checker has five tests, which also run offline: cd labs && python -m pytest skill-example printed "5 passed". One of them pastes a fake secret into an example file and checks it never reaches the output.

To use the skill with Claude Code, copy the folder to .claude/skills/ in a project of your own (or to ~/.claude/skills/ for yourself); nothing installs itself. Time: 15 minutes to read and run; any laptop, no API key.

Try it

A team has 25 skills whose descriptions average 120 tokens and whose bodies average 3,000 tokens. A typical task triggers one skill and reads one 800-token reference file. How many skill tokens does the task use, and how many would it use if every body were in the system prompt instead?

Answer

With skills: 25 × 120 = 3,000 for the descriptions, plus 3,000 for one body and 800 for the reference file: 6,800 tokens. With every body in the system prompt: 25 × 3,000 = 75,000 tokens, before any reference file, on every task.

Build it

In labs/skill-example/ you can run the checker against the demo projects, change a README row to make it fail, and then write a second skill of your own with a script that checks something exact. Copy the folder into .claude/skills/ to try it in a coding agent.

Self-check

Which part of a skill is in the context all the time?

Only its name and description, about 100 tokens. The body loads when the skill is triggered, and bundled files only when read.

What two things must a description say?

What the skill does and when the agent should use it.

Why does the example skill use a script for the comparison instead of asking the agent to compare the files?

A script gives the same exact answer every time, costs no reasoning, and can be trusted not to print secret values. Comparing dozens of names by eye is where an agent slips.

What should you check before installing a skill someone else wrote?

Every bundled file, for unexpected network calls, file access or instructions to fetch outside content, because the agent will follow and run them with its own permissions.