Before you start
You need Claude Code, or any agent that reads SKILL.md, and a terminal. The lesson edits one file. The skill's instructions can be a single line for now, since the description is the part under test. Lesson 2 fills in the body.
The running example is a skill that reviews changes to an OpenAPI spec. It was written for this course. The commands come from the Agent Skills and Claude Code documentation listed under Sources.
Every fact here comes from the pages under Sources, read on 4 November 2026. This lesson is not hands-on testing, and the sample skill was written for it.
Rewrite a vague description in six steps
Anthropic's authoring guide says Claude uses the description to choose a skill from potentially more than 100. It also says the description is injected into the system prompt, so it belongs in the third person: "Processes Excel files", not "I can help you process Excel files".
Most first drafts describe the skill: "Helps with API changes." The Agent Skills specification uses "Helps with PDFs." as its own example of a poor description. The version below says what the skill does, when to use it, and covers the user who never says "OpenAPI".
---
name: reviewing-api-changes
description: Reviews changes to an OpenAPI or Swagger spec for breaking changes such as removed fields, renamed paths and stricter validation. Use when the user asks whether an API change is safe to ship, compares two versions of an API, or edits a spec file, even if they never say "breaking change".
---
# Reviewing API changes
Instructions come in lesson 2.
- Make the folder with
mkdir -p ~/.claude/skills/reviewing-api-changes. For one repository only, create.claude/skills/reviewing-api-changesinside it. - Pick the name. The specification allows lowercase letters, numbers and hyphens, up to 64 characters, and the name has to match the folder. Anthropic suggests gerunds such as
processing-pdfs, avoidshelperandutils, and bars the wordsanthropicandclaude. - Save a first draft as SKILL.md with the line
description: Helps with API changes.That is the version to beat. - Rewrite it in two halves. First what the skill does, in concrete verbs: reviews a spec for removed fields, renamed paths and stricter validation. Then "Use when", followed by the situations.
- Add the requests that never name the topic. The Agent Skills guide tells you to list contexts where the skill applies even if the user doesn't explicitly mention the domain, so the sample ends with
even if they never say "breaking change". - Save the file, then ask Claude Code
What skills are available?to confirm the skill is listed. Ask for the job in your own words, for example "can I ship this API change?". If nothing loads, run/reviewing-api-changesto call it by name.
What the agent reads before it decides
At startup an agent loads only the name and description of each skill. When a request matches, it reads the whole SKILL.md. The Agent Skills guide draws the conclusion itself: the description carries the entire burden of triggering.
One nuance changes how you test. Agents tend to consult a skill only for work that needs knowledge or capabilities beyond what they manage alone, so a simple one-step request can skip a skill whose description matches perfectly. A skill earns its trigger on specialized work: an unfamiliar format, a house convention, a workflow with a fixed order.
Claude Code adds a limit of its own. It joins two fields, description and when_to_use, and cuts the combined text in its skill listing, so a key phrase placed last may never reach the model. With dozens of skills installed, the whole listing has a budget too, and it drops the descriptions of the least-used skills first.
~100
tokens of context per skill for its name and description, loaded at startup
Source: Claude Platform docs: Agent Skills (read November 4, 2026)
1,024
characters at most in a description under the open specification
Source: Agent Skills specification (read November 4, 2026)
1,536
characters of description and when_to_use together that Claude Code keeps in its skill listing
Source: Claude Code docs: Skills (read November 4, 2026)
1%
of the model's context window is the budget for the whole skill listing in Claude Code
Source: Claude Code docs: Skills (read November 4, 2026)
| Description | What the agent can do with it |
|---|---|
Helps with API changes. | Nothing specific to match. No situation, no words a user would type. |
I can help you review API changes. | First person. Anthropic warns that mixed points of view can cause discovery problems. |
Reviews OpenAPI or Swagger spec changes for breaking changes. Use when the user asks whether an API change is safe to ship, even if they never say "breaking change". | Says what the skill does and when to act, and covers a request that doesn't name the topic. |
When the skill stays silent
Check the YAML first. If the frontmatter doesn't parse, Claude Code still loads the body but with empty metadata, so /reviewing-api-changes works and automatic matching never does. Running claude --debug prints the parse error, and claude plugin validate ~/.claude/skills lists SKILL.md files whose frontmatter fails (Claude Code v2.1.233 or later).
When the YAML is fine, Claude Code's documentation gives an order for the rest, shown below. Past it, look at the listing itself. /doctor estimates what the skill listing costs in context, and /skill-doctor (v2.1.252 or later) shows what each skill costs and how often it runs.
The opposite problem, a skill that fires on the wrong requests, has two fixes in the docs: a more specific description, or disable-model-invocation: true so the skill runs only when you type its command. The Agent Skills guide adds a third, which is to say in the description what the skill does not do where it borders another skill.
Read the description for keywords
Does it hold the words a user would naturally say?
Ask "What skills are available?"
The skill has to appear in the answer.
Rephrase the request
Try wording closer to the description.
Run /skill-name
If the skill is user-invocable, calling it by name separates a matching problem from a loading problem.
Check the name
If the command isn't recognized either, Claude Code may have refused the name, for example one with a no-break space or an angle bracket.
Check paths
A skill that sets
pathsactivates only for files inside Claude's current working directory.
What Alex Albert and Boris Cherny of Anthropic say a skill is for
Alex Albert, who works in research at Anthropic, introduced Skills on X in October 2025. His launch post calls them packaged knowledge that Claude loads on demand. That is why this lesson spends its time on one field: until a request matches, the description is all of the skill that Claude holds in context.
Boris Cherny, who created Claude Code, shared the Claude Code team's tips at the end of January 2026. One is a rule for when a skill is worth writing at all: a job you do more than once a day. Put that daily job into the "Use when" half, in the words you use when you ask for it, and the skill has a request to match.
If you do something more than once a day, turn it into a skill or command
Screenshots of X's own embeds of the posts, taken on 5 November 2026, with the time in UTC. X cuts the first post short with Show more. Select a screenshot to open the post on X.
Common mistakes
- Describing the skill instead of the trigger. "Helps with X" says what it is, not when to reach for it.
- Pasting the words from the one prompt that failed. The Agent Skills guide calls that overfitting and asks you to find the general category the failed prompts share.
- Putting the main use case last. Claude Code trims the combined description and
when_to_usetext, and the end goes first. - Writing angle brackets. Claude Code shows them in a description as
<and>, so use square brackets for placeholders. - Adding
when_to_useto a skill that travels. Claude Code reads it, but claude.ai uploads accept only the specification's six fields, and an extra key fails the upload.
Try it yourself
Take a skill you already have, or the one from this lesson, and write six prompts on a sheet of paper. Three should load the skill and three should not. Make one of the three positives avoid the skill's topic words. Make two of the negatives near-misses that share words with the skill, such as a request to write an OpenAPI spec from scratch.
Run each prompt in a fresh session and mark hit or miss. Keep the sheet. Lesson 3 turns it into a repeatable test.
- Do the first words name the job, in concrete verbs?
- Does it say when to use the skill?
- Is it in the third person?
- Does the main use case come first?
- Does one phrase work for a user who never names the topic?
Next
A description that fires is half the work. Lesson 2 covers what the skill does once it has loaded: what stays in SKILL.md, what moves into references/ and scripts/, and how to tell the agent when to open each file.
The limits that differ between claude.ai, the open specification and Claude Code sit in one table in how to create an Agent Skill, and what are Agent Skills covers the format itself. Skills other people wrote are listed as kits on Mindket, if you want to read descriptions from other authors.
Check yourself
Which description is written the way this lesson recommends?
Show answer
C.
Reviews OpenAPI spec changes for breaking changes. Use when the user asks whether an API change is safe to ship.It says what the skill does and when to act, in the third person, while the other two are vague or in the first person.A skill works when you type its slash command but never triggers on its own. What do you check first?
Show answer
A. Whether the frontmatter parses, for example with
claude --debugBroken frontmatter still loads the body with empty metadata, so the command works and automatic matching never does.Where in the description should the main use case go, and why?
Show answer
D. At the start, because Claude Code trims long descriptions from the end Claude Code trims the combined description text in its skill listing, so a key phrase placed last may never reach the model.
A skill fires on requests it should not handle. Which fix keeps it, but runs it only when you type its command?
Show answer
B. Set
disable-model-invocation: trueWithdisable-model-invocation: truethe skill runs only when you type its command, and a more specific description is the other fix.
Frequently asked questions
How long can a skill description be?
Up to 1,024 characters under the open Agent Skills specification, though a few sentences is usually enough. Claude Code keeps 1,536 characters of description and when_to_use together in its skill listing, so the main use case goes first.
Can one description work in Claude Code, Codex and Cursor?
Mostly, yes. OpenAI's guide for Codex asks for concise descriptions that front-load the use case and trigger words and say when the skill should and shouldn't trigger. Cursor's docs define the field the same way, as what the skill does and when to use it. Keep extras such as when_to_use out of a skill that travels.
What is when_to_use in Claude Code?
It is an optional field for extra trigger context, such as trigger phrases or example requests. Claude Code appends it to the description in its skill listing and counts it toward the same cut-off. It isn't part of the open specification, so a skill that travels is safer with everything in description.
Why does Claude load my skill on some runs and not others?
Model behavior isn't deterministic, so the same request can load a skill on one run and miss on the next. The Agent Skills guide suggests running each test prompt several times, three as a starting point, before you judge a description.
Do I have to write "Use when" in the description?
No rule requires those words. The description has to say when to act. The Agent Skills guide recommends imperative phrasing such as "Use this skill when..." because the agent is deciding whether to act, and the sentence tells it.
Can Claude write the description for me?
Yes. Anthropic says Claude handles the skill format natively, so you can ask it to draft one. For tuning, Anthropic's skill-creator plugin generates should-trigger and should-not-trigger prompts, measures the hit rate and proposes edits. Lesson 3 shows how.
Sources
- Agent Skills specification https://agentskills.io/specification
- Agent Skills: Optimizing skill descriptions https://agentskills.io/skill-creation/optimizing-descriptions
- Claude Platform docs: Skill authoring best practices https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
- Claude Platform docs: Agent Skills https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
- Claude Code docs: Skills https://code.claude.com/docs/en/skills
- OpenAI: Build skills (Codex) https://learn.chatgpt.com/docs/build-skills
- Cursor docs: Agent Skills https://cursor.com/docs/context/skills
- Boris Cherny on X: tips from the Claude Code team, skills, 31 January 2026 https://x.com/bcherny/status/2017742748984742078
- Alex Albert on X: introducing Skills, 16 October 2025 https://x.com/alexalbert__/status/1978877498411880550