Skills Trigger Mechanism
Skills are not "called" by the user; Claude independently decides whether to use them.
Understanding this trigger mechanism helps you write Skills that are more easily and accurately triggered.
How the Trigger Mechanism Works
When Claude starts, it loads all available Skills'nameanddescriptioninto the context.
After the user sends a message, Claude determines: Does this task require me to consult a Skill?
There is only one basis for this decision:The Skill's description field。
The body of SKILL.md does not participate in trigger evaluation. Only after Claude decides to use a Skill does it read the body content.
Trigger Flow Diagram
What Kinds of Tasks Trigger a Skill
Not all requests that match the description will trigger a Skill.
Claude has an internal judgment:Is this task complex enough to require referring to specialized instructions?
| Request Type | Example | Whether the Skill Is Triggered | Reason |
|---|---|---|---|
| Simple single-step task | "Read this PDF" | Usually not triggered | Claude handling it directly is more efficient |
| Complex multi-step task | "Extract tables from the PDF and convert them to Excel" | Triggered | Requires a specialized workflow |
| Professional domain operation | "Merge three PDFs and add a watermark" | Triggered | Involves a specific toolchain |
| Output has clear format requirements | "Generate a Word report that conforms to our company's template" | Triggered | Requires specific formatting standards |
If your Skill is rarely triggered, it is usually because the task description is too simple, or the description is not precise enough. When testing, use complex, specific user requests.
Description Trigger Strategies
The description is the only credential for triggering, and its wording directly determines trigger accuracy.
Strategy 1: List Specific Scenarios
Don't just write "what this Skill does"; also write "in what situations it should be used".
# 不推荐：只描述功能 description: 处理 Excel 文件。 # 推荐：描述功能 + 触发场景 description: > 处理 Excel 和 CSV 文件，包括：读取数据、清洗格式、生成图表、 计算统计指标、合并多个表格。当用户提到 Excel、xlsx、CSV、 表格数据、数据清洗、财务报表时，应优先使用此 Skill。
Strategy 2: Use "Action-Oriented" Language
The Skills system naturally tends to trigger sparingly. Adding action-oriented language to the description can increase the trigger rate.
description: > 生成专业的 PowerPoint 演示文稿。当用户需要制作幻灯片、PPT、演讲稿、 汇报材料时，必须使用此 Skill，即使用户没有明确说"用 pptx 格式"。 只要涉及演示文稿的创建或修改，都应触发此 Skill。
Strategy 3: List Keywords
Appending a list of trigger keywords at the end of the description is a simple and effective supplementary measure.
description: > 代码审查助手，分析代码质量、发现潜在 Bug、给出改进建议。 关键词：code review、代码审查、代码分析、bug 检查、 重构建议、代码质量、静态分析。
Trigger Conflicts: Multiple Skills Match at the Same Time
When a user's request may match multiple Skills, Claude selects the most relevant one based on the degree of match.
To avoid conflicts, keep clear boundaries among the descriptions of different Skills.
| Conflict Scenario | Solution |
|---|---|
| Two Skills both handle PDFs | Distinguish specific operations in the description, such as "PDF creation" vs. "PDF reading" |
| Overlap between a general Skill and a specialized Skill | In the description of the specialized Skill, explicitly state scenarios that differentiate it from the general Skill |
| Two Skills with similar functions | Consider merging them into one Skill and handle different cases through internal branching |
A Skill's description should describe its applicable scenarios in an "exclusive" manner, not merely describe what it "can do". What it can do ≠ when it should be used.
Use the Description Optimization Tool to Test Triggering
The skill-creator Skill provides a description optimization script that automatically evaluates trigger accuracy.
Example
# --eval-set: test case file path
# --skill-path: path to the Skill to be optimized
# --max-iterations: maximum number of iterations
python -m scripts.run_loop \
--eval-set evals/trigger-eval.json \
--skill-path my-skill/ \
--model claude-sonnet-4-20250514 \
--max-iterations 5 \
--verbose
The script automatically runs tests, evaluates scores, modifies the description, and outputs the best result.
For detailed description optimization methods, see Article 24:Skills Description Optimization Tips。
Other Extensions