Why a skill does not trigger, and how to fix its description

A skill only helps if your agent loads it. The agent does not read all your skills on every request: it decides from a short description. Most skills that seem not to work actually have a description that does not match how you phrase your requests.

How the agent picks a skill

Agents load skills in stages so they do not clutter their context.

1. At startup, the agent reads only the name and description of each installed skill. The Agent Skills specification puts this at roughly 100 tokens per skill.
2. When your request matches a description, it reads the full SKILL.md file and follows its instructions.
3. While working, it opens supporting files (references, templates, scripts) only if it needs them.

The description therefore carries the whole burden of triggering. If it does not say when the skill is useful, the agent has no reason to reach for it. A less obvious consequence: an agent mostly consults skills for tasks that need knowledge it lacks on its own. A simple one-step request such as "read this PDF" may trigger nothing even with a perfect description, because the agent can manage with its basic tools.

Why it does not trigger

Four points specific to Claude Code, from its documentation:

• The description and the optional when_to_use field are truncated together at 1,536 characters in the skill list. Put the main use case first.
• That list has a character budget equal to 1% of the model's context window. When it overflows, Claude Code drops the descriptions of the skills you invoke least. The names stay, but not the keywords that let Claude recognize them.
• If the YAML frontmatter is malformed, the skill loads with empty metadata: /skill-name still works, but the agent can no longer match it from its description. The frontmatter is read only when the --- line is the very first line of the file. Run Claude Code with --debug to see the parse error.
• A skill with disable-model-invocation set to true never triggers on its own: its description is not even in the context.

To see which skills Claude can see, ask it "What skills are available?". If a skill is missing there, the problem is the installation, not the description. The Claude Code page lists the folders to check.

Writing a description that triggers

Here is the header of a skill with a description that is too vague:

---
name: pdf-tools
description: Helps with PDFs.
---

And a version that says both what the skill does and when to use it:

---
name: pdf-tools
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction, even if they do not say "PDF" explicitly.
---

The rules to keep, from the Agent Skills specification and its description guide:

• Say what the skill does and when to use it. A description is 1 to 1,024 characters.
• Address the agent. "Use this skill when…" works better than "This skill does…": the agent is deciding whether to act, so tell it when.
• Start from the user's intent, not from the skill's internals. The agent compares the description with what you ask.
• List the situations, including indirect ones. Add cases where you do not name the domain, such as a request about "margins" for a spreadsheet skill.
• Keep it short. A few sentences are enough, and every description takes up context in all your conversations.

Avoid angle brackets in the description: Claude Code displays them as < and >. Use square brackets for a placeholder, for example [branch].

Test and adjust

Do not judge a description from a single try. The Agent Skills guide recommends preparing realistic requests, some that should trigger the skill and some that should not, then recording the result after each change.

1. Write about ten requests as you really phrase them, with typos, shortcuts and context.
2. Add a few neighboring requests that should not trigger the skill, to catch a description that is too broad.
3. Run each request in a fresh session and note whether the agent loads the skill.
4. Edit the description, then repeat.

If the skill fires too often, make the description more specific. In Claude Code you can also add disable-model-invocation: true and start it by hand only, which suits actions with side effects such as a deployment.

A skill that has loaded can still be dropped along the way. Claude Code adds its content to the conversation when it is invoked, and after an automatic summary of the context it keeps only the start of each invoked skill. Put the essential instructions at the top of SKILL.md, and invoke the skill again if the agent drifts from it.

To install a first resource, see Install your first resource. To understand what a skill adds over a prompt, see Resource or plain prompt?. You can browse the catalog on the skills page.