# Skill description: write the name and description so your skill loads

> A skill description is the one thing an agent reads about your skill before it decides to open it. Write it as an instruction: what the skill does, then when to use it, in the words people type. This lesson turns a vague description into one that works and shows how to fix a skill that never fires.

Mindket editors · Published 2026-11-04 · Updated 2026-11-05 · https://mindket.com/learn/agent-skills/skill-description

## In short

- Write the description as what the skill does plus when to use it, in the third person.
- Name the situations, including ones where the user never says the skill's topic.
- Put the main use case first, because Claude Code trims long descriptions in its skill listing.
- When a skill stays silent, check keywords, the skills list, a rephrased request and the slash command, in that order.

## 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) 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](https://agentskills.io/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".

````markdown
---
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.

````

1. Make the folder with `mkdir -p ~/.claude/skills/reviewing-api-changes`. For one repository only, create `.claude/skills/reviewing-api-changes` inside it.
2. 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`, avoids `helper` and `utils`, and bars the words `anthropic` and `claude`.
3. Save a first draft as SKILL.md with the line `description: Helps with API changes.` That is the version to beat.
4. 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.
5. 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"`.
6. 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-changes` to 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](https://agentskills.io/skill-creation/optimizing-descriptions) 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](https://code.claude.com/docs/en/skills), `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.

**The numbers behind a description**

- **~100** tokens of context per skill for its name and description, loaded at startup (Source: [Claude Platform docs: Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview), read 2026-11-04)
- **1,024** characters at most in a description under the open specification (Source: [Agent Skills specification](https://agentskills.io/specification), read 2026-11-04)
- **1,536** characters of description and when_to_use together that Claude Code keeps in its skill listing (Source: [Claude Code docs: Skills](https://code.claude.com/docs/en/skills), read 2026-11-04)
- **1%** of the model's context window is the budget for the whole skill listing in Claude Code (Source: [Claude Code docs: Skills](https://code.claude.com/docs/en/skills), read 2026-11-04)

| 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](https://code.claude.com/docs/en/skills) 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.

**Claude Code's checks for a skill that doesn't trigger**

1. Read the description for keywords. Does it hold the words a user would naturally say?
2. Ask "What skills are available?". The skill has to appear in the answer.
3. Rephrase the request. Try wording closer to the description.
4. Run /skill-name. If the skill is user-invocable, calling it by name separates a matching problem from a loading problem.
5. 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.
6. Check paths. A skill that sets `paths` activates 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](https://x.com/alexalbert__/status/1978877498411880550) 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](https://x.com/bcherny/status/2017742748984742078) 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
>
> Boris Cherny, Creator of Claude Code, Anthropic, [X](https://x.com/bcherny/status/2017742748984742078) (read 2026-11-05)

[![Boris Cherny (@bcherny) on X, 31 January 2026, tip 4 from the Claude Code team. Create your own skills and commit them to git. Reuse across every project. If you do something more than once a day, turn it into a skill or command.](https://mindket.com/blog/shots/x-bcherny-skill-once-a-day.webp?v=40f26e518b33)](https://x.com/bcherny/status/2017742748984742078)

Boris Cherny on X, 31 January 2026

[![Alex Albert (@alexalbert__) on X, 16 October 2025. Today we're introducing Skills in claude dot ai, Claude Code, and the API. Skills let you package specialized knowledge into reusable capabilities that Claude loads on demand as agents tackle more complex tasks.](https://mindket.com/blog/shots/x-alexalbert-skills-load-on-demand.webp?v=91fd7c3a00ba)](https://x.com/alexalbert__/status/1978877498411880550)

Alex Albert on X, 16 October 2025

> 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_use` text, 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_use` to 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](https://mindket.com/learn/agent-skills/skill-scripts-and-references) 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](https://mindket.com/blog/how-to-create-agent-skill), and [what are Agent Skills](https://mindket.com/blog/what-are-agent-skills) covers the format itself. Skills other people wrote are listed as [kits on Mindket](https://mindket.com/kits), if you want to read descriptions from other authors.

## Check yourself

1. Which description is written the way this lesson recommends?

   A. `Helps with API changes.`
   B. `I can help you review API changes.`
   C. `Reviews OpenAPI spec changes for breaking changes. Use when the user asks whether an API change is safe to ship.`

   Answer: C. 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.

2. A skill works when you type its slash command but never triggers on its own. What do you check first?

   A. Whether the frontmatter parses, for example with `claude --debug`
   B. Whether the skill folder sits in `.github/skills/`
   C. Whether the description is shorter than 100 characters

   Answer: A. Broken frontmatter still loads the body with empty metadata, so the command works and automatic matching never does.

3. Where in the description should the main use case go, and why?

   A. At the end, because agents read the last words most closely
   B. In the `name` field, because that is read first
   C. In the middle, because Claude Code keeps the middle of long text
   D. At the start, because Claude Code trims long descriptions from the end

   Answer: D. Claude Code trims the combined description text in its skill listing, so a key phrase placed last may never reach the model.

4. A skill fires on requests it should not handle. Which fix keeps it, but runs it only when you type its command?

   A. Delete the `description` field
   B. Set `disable-model-invocation: true`
   C. Set `user-invocable: false`

   Answer: B. With `disable-model-invocation: true` the 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](https://learn.chatgpt.com/docs/build-skills) 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](https://cursor.com/docs/context/skills) 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) (read 2026-11-04)
- [Agent Skills: Optimizing skill descriptions](https://agentskills.io/skill-creation/optimizing-descriptions) (read 2026-11-04)
- [Claude Platform docs: Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) (read 2026-11-04)
- [Claude Platform docs: Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) (read 2026-11-04)
- [Claude Code docs: Skills](https://code.claude.com/docs/en/skills) (read 2026-11-04)
- [OpenAI: Build skills (Codex)](https://learn.chatgpt.com/docs/build-skills) (read 2026-11-04)
- [Cursor docs: Agent Skills](https://cursor.com/docs/context/skills) (read 2026-11-04)
- [Boris Cherny on X: tips from the Claude Code team, skills, 31 January 2026](https://x.com/bcherny/status/2017742748984742078) (read 2026-11-05)
- [Alex Albert on X: introducing Skills, 16 October 2025](https://x.com/alexalbert__/status/1978877498411880550) (read 2026-11-05)

[Browse kits](https://mindket.com/kits)