注册
Claude其他 AI 工具

Skill 不触发怎么办：description 怎么写才会被调用，附 Claude Code 排查步骤

装了 Skill 却不被调用、或者乱触发？按 Agent Skills 官方指南和 Claude Code 文档讲清触发原理、description 的四条写法、用 20 条测试问句验证触发率的方法，以及 Claude Code 里描述被截断、YAML 写错等情况的排查命令。

NNathaniel bigo··原创首发·AI 辅助撰写
10 分钟读完
资料核对于 2026-10-11 · 依据官方文档与公开资料整理 免费账号 账号
本文根据 Agent Skills 官方指南《Optimizing skill descriptions》和 Claude Code 官方文档的 Troubleshooting 一节整理，资料核对于 2026-10-11。排查命令以 Claude Code 为例，其他工具的思路相同、命令不同。

适用于谁

  • 搜「skill 不触发」「如何触发 skill」「skill 触发词」的人；
  • Skill 明明装好了，说了相关的话 Claude 却不用它的人；
  • 反过来，Skill 在不相干的任务里乱跳出来的人；
  • 看到「skill descriptions were shortened to fit the skills context budget」这类提示不知道什么意思的人。

结论先说

  1. 触发只看 description。智能体启动时只加载每个 Skill 的名称和描述，任务和描述对得上才会去读正文。正文写得再好，描述没写清「什么时候用」也不会被调用。
  2. 简单任务本来就不一定触发。官方说明：智能体一般只在自己搞不定的任务上才去查 Skill，「读一下这个 PDF」这种一步就能完成的请求，即使描述完全匹配也可能不触发。
  3. 不触发先做四件事：确认 Skill 被发现了、检查 YAML 有没有写错、看描述有没有被截断、把描述改成「Use this skill when...」的写法。
  4. 乱触发就把描述写窄，或者关掉自动调用、只留手动调用。
  5. 想认真调，就做测试集：约 20 条问句，一半该触发一半不该触发，每条跑 3 次算触发率。

一、触发是怎么发生的

三步：

  1. 启动时，智能体读入所有 Skill 的 name 和 description；
  2. 你提出任务，智能体把任务和这些描述做匹配；
  3. 匹配上了，才把对应的 SKILL.md 全文读进上下文并照着做。

官方的说法是：description 承担了触发的全部责任。

二、description 的四条写法

来自《Optimizing skill descriptions》：

原则说明
用祈使句写「Use this skill when...」，而不是「This skill does...」。智能体在判断要不要行动，就直接告诉它何时行动
写用户意图，不写实现描述用户想达成什么，而不是 Skill 内部用了什么库、分几步
宁可主动一点明确列出适用场景，包括用户没有直接说出领域名称的情况
保持简短几句话到一小段；规范的硬上限是 1024 字符

官方给的修改前后对比：

yaml
# 修改前
description: Process CSV files.

# 修改后
description: >
  Analyze CSV and tabular data files — compute summary statistics,
  add derived columns, generate charts, and clean messy data. Use this
  skill when the user has a CSV, TSV, or Excel file and wants to
  explore, transform, or visualize the data, even if they don't
  explicitly mention "CSV" or "analysis."

改后的版本对「做什么」更具体（统计、派生列、图表、清洗），对「什么时候用」更宽（CSV、TSV、Excel，没提关键词也算）。

三、Claude Code 里的排查步骤

1. Skill 有没有被发现

官方列的检查顺序：

  1. 描述里有没有用户自然会说的关键词；
  2. 问一句 What skills are available?，看它在不在列表里（或者输入 /skills 查看）；
  3. 换一种更贴近描述的说法再试；
  4. 直接输入 /技能名 手动调用，确认 Skill 本身能工作。

如果手动调用正常、自动不触发，问题就在描述或下面两项。

2. YAML 有没有写错

官方说明：frontmatter 的 YAML 格式不对时，Claude Code 仍会加载正文，但元数据是空的，于是 /技能名 能用，Claude 却没有描述可以匹配。

  • 加 --debug 启动可以看到解析错误；
  • 批量检查可以运行 claude plugin validate .claude/skills（项目 Skill）或 claude plugin validate ~/.claude/skills（个人 Skill）。官方注明这个用法需要较新的版本。

3. 描述是不是被截断了

Skill 装得多时会出现这个问题。官方文档的说明：

  • Claude Code 把所有 Skill 的名称和描述组成一份清单放进上下文。清单始终包含每个 Skill 的名称，但总量超出预算时会丢掉一部分描述，被丢掉描述的 Skill 就失去了用来匹配的关键词；
  • 预算按模型上下文窗口的 1% 计算；
  • 超出时，从你最少调用的 Skill 开始丢，常用的保留完整描述；
  • 每个 Skill 的 description 加 when_to_use 合计最多显示 1,536 个字符，超出部分截掉。

怎么查、怎么办：

目的做法
看清单占了多少上下文、谁占得最多运行 /doctor
找出装了却从没用过的 Skill运行 /skill-doctor
调大预算设置 skillListingBudgetFraction（例如 0.02 即 2%），或用环境变量 SLASH_COMMAND_TOOL_CHAR_BUDGET 指定固定字符数
给其他 Skill 腾地方在 skillOverrides 里把优先级低的设为 "name-only"，只列名称不列描述
从源头压缩精简描述，把最关键的使用场景写在最前面

4. 是不是被设成了只能手动调用

frontmatter 里有 disable-model-invocation: true 的 Skill，描述不会进入上下文，Claude 不会自动调用，只能你输入 /技能名。从别处拿来的 Skill 不触发时，记得看一眼这个字段。

四、乱触发怎么办

官方给的两条：

  1. 把描述写得更具体。可以写明这个 Skill 不做什么，或者说清它和相邻能力的边界；
  2. 只想手动调用，就加 disable-model-invocation: true。有副作用的 Skill（部署、发消息）官方本来就建议这样设。

五、一开始照着做、后来不照做了

这是另一类问题，官方按原因分了三种：

现象原因与办法
跳过了一条必须每次都遵守的规则Skill 里的话是「请求」，不是保证。把规则改成 Hook，由 Claude Code 在每次事件发生时强制执行
跳过了一条需要判断着用的建议Skill 内容只在调用时加载一次，之后不会重读。把措辞改成覆盖整个任务的说法，例如「每次修改后都运行测试」而不是「运行测试」
对话被压缩过压缩后每个 Skill 只保留开头的一部分。重新调用一次即可恢复，并把最重要的说明放在 SKILL.md 靠前的位置

六、认真调：做一套触发测试

官方推荐的方法，适合要发布给别人用的 Skill。

1. 准备约 20 条问句，8–10 条应该触发、8–10 条不应该触发：

json
[
  { "query": "I've got a spreadsheet in ~/data/q4_results.xlsx with revenue in col C and expenses in col D — can you add a profit margin column and highlight anything under 10%?", "should_trigger": true },
  { "query": "whats the quickest way to convert this json file to yaml", "should_trigger": false }
]
  • 应该触发的：说法要多样，有正式有随意，有的直接点名领域、有的只描述需求；最有价值的是「Skill 能帮上忙，但从字面看不明显」的问句；
  • 不应该触发的：要选擦肩而过的。和 Skill 共用关键词、实际需要的却是别的东西。「今天天气怎么样」这种毫不相干的问句测不出任何东西；
  • 写得像真人：带文件路径、带背景（「领导让我……」）、带口语和偶尔的错别字。

2. 每条跑 3 次，算触发率。 模型的行为不是确定的，同一句话这次触发下次可能不触发。触发率高于 0.5 算触发。

3. 留出验证集。 约 60% 用来发现问题、指导修改，约 40% 只用来检验修改是否真的通用，避免把描述调成只对这几句话有效。

4. 循环修改，官方的提醒：

  • 该触发的没触发：描述太窄，扩大范围；
  • 不该触发的触发了：描述太宽，加上边界；
  • 不要把失败问句里的词直接塞进描述，那是过拟合，要找出这些问句代表的那一类情况；
  • 改了几轮没进展，就换一种句式结构重写，而不是继续小修小补；
  • 一般五轮足够。再不行，问题可能在测试问句本身。

5. 选验证集通过率最高的那一版，不一定是最后一版。

官方提到，Anthropic 的 skill-creator 技能可以把这套流程自动跑完；Skill 放在插件里时，Claude Code 还可以用 claude plugin eval 配合 tool_used: Skill 评分器批量测试。

常见问题

Q：有没有「触发词」这种东西？

没有固定的触发词机制。智能体是拿任务和描述做语义匹配，描述里出现用户常说的词会有帮助，但不是命中某个词就一定触发。

Q：description 用中文写可以吗？

规范没有语言限制。按你平时提需求的语言来写，更容易对得上。

Q：其他工具也是这样吗？

基于 SKILL.md 的工具触发原理相同：先看描述，再读正文。具体的查看命令和截断规则各家不同，例如 Codex 的文档写的是清单最多占上下文窗口的 2%，装得多时先缩短描述。

Q：个人 Skill 文件夹不见了？

Claude Code 文档有专门一节：先看 ~/.claude/skills/.trash/ 里有没有，把文件夹移回 ~/.claude/skills/ 即可恢复；回收目录里的内容默认 30 天后清理。

参考资料

  • Optimizing skill descriptions（Agent Skills 官方）：https://agentskills.io/skill-creation/optimizing-descriptions
  • Extend Claude with skills · Troubleshooting（Claude Code 官方）：https://code.claude.com/docs/en/skills
  • Extend Claude Code（Claude Code 官方）：https://code.claude.com/docs/en/features-overview
需要开通或续费？Claude Pro 充值 →

Nathaniel 的更多内容

  1. 01

    promptfoo 使用教程：对比提示词和模型、写断言自动评测（安装与配置）

    promptfoo 是什么、怎么使用？按官方 README 和入门文档讲清它的用途、三种安装方式、用示例项目起步、promptfooconfig.yaml 里提示词、模型和测试用例三部分怎么写、常用断言类型的含义、eval 与 view 两条命令，以及把它放进日常改提示词流程的方法。

    ChatGPT其他 AI 工具0
  2. 02

    Kimi API怎么用：API Key获取、Python调用、K3价格与429报错处理

    Kimi API Key 在哪里获取、怎么用 Python 调用 K3、价格怎么算、429 和 401 报错怎么办？本文按 Kimi API 开放平台官方文档讲清注册认证、创建 Key、base_url 与模型名、计费规则和常见错误排查。

    Kimi0
  3. 03

    Cursor Agent 模式怎么用：Agent、Plan、Ask 三种模式，检查点回滚与消息排队

    Cursor Agent 模式是什么、和 Plan / Ask 模式怎么选？按官方文档讲清 Agent 能调用哪些工具、Shift+Tab 切换模式、Plan 模式先出方案再动手、用检查点撤销改动、任务进行中排队或插话，以及 /goal 长目标。

    Cursor0
  4. 04

    Gemini 聊天记录怎么导出：导出到文档 / 表格、生成 PDF 与用 Takeout 批量导出完整对话

    Gemini 没有「一键导出全部对话」的按钮，但有三条官方路径：单条回答导出到 Google 文档、Gmail、表格；让 Gemini 直接生成 PDF、Word、Markdown 文件；用 Google Takeout 批量下载全部活动记录。本文给出每种方法的步骤和限制。

    Gemini0
  5. 05

    ChatGPT 生成图片中文乱码、文字错误怎么办：7 个按顺序试的办法

    让 ChatGPT 做海报、封面、信息图，中文总是缺笔画、错字、乱码？本文按 OpenAI 官方图像提示指南，给出从写法、字数、局部修改、质量档位到后期排版的 7 个办法，以及什么时候干脆别让 AI 写字。

    ChatGPT0
  6. 06

    OpenCode Skills 使用指南：技能目录、命名规则、权限配置与不加载排查

    OpenCode 的 Skills 放在哪个目录、怎么控制哪些技能能用？按 OpenCode 官方文档讲清六个扫描位置、name 的正则规则、skill 工具的工作方式、在 opencode.json 里用 allow / deny / ask 配置权限、按智能体覆盖，以及技能不出现时的五项检查。

    其他 AI 工具0

同产品的其他教程

  1. 01

    Cursor、Claude Code、Codex、GitHub Copilot 有什么区别：按形态、账号、计费和规则文件对比

    Cursor 和 Claude Code 的区别是什么、和 Codex、GitHub Copilot 怎么选？只用各家官方文档的事实对比：产品形态、用什么账号、怎么计费、能选哪些模型、规则文件与 MCP、权限模式、代码审查；不做「谁更强」的排名，给出按场景选择的思路。

    ClaudeCursor0
  2. 02

    如何让大模型稳定输出 JSON：结构化输出、JSON 模式与提示词写法（OpenAI / Claude）

    怎么让大模型稳定输出 JSON？本文按 OpenAI 和 Anthropic 官方文档讲清只靠提示词、JSON 模式、结构化输出三种做法的可靠程度，两家的写法与 Schema 限制，以及拒答和截断两种例外。

    ChatGPTClaude0
  3. 03

    MinerU 是什么、怎么用：把 PDF 等文档解析成 Markdown（4.0 的安装、四档解析与命令）

    MinerU 是什么、怎么安装使用？按官方中文 README 讲清 4.0 版本的定位、支持的输入与输出格式、flash / basic / standard / advanced 四档解析各适合什么、pip 安装命令、mineru-kit 与 mineru 两个命令的分工和常用写法，以及从旧版升级要注意什么。

    其他 AI 工具0
  4. 04

    npx skills add 怎么用：从 GitHub 安装 Skill、skills.sh 是什么与常用命令

    网上的 Skill 安装命令大多是 npx skills add 开头，它是什么、装到哪去了？按官方 README 讲清 skills 命令行工具支持的来源写法、项目与全局两种范围、-a 指定工具、list / find / update / remove 等命令、软链接与复制的区别，以及怎么关掉遥测。

    Claude其他 AI 工具0
  5. 05

    即梦首尾帧怎么用：两张图生成过渡视频（在哪里、提示词、不能用怎么办）

    即梦首尾帧在哪里、怎么用？本文讲清首尾帧入口、哪些模型支持、两张图的比例要求、过渡提示词怎么写，以及「首尾帧不见了 / 不能用了」「画面跳变」的原因和解决办法。

    其他 AI 工具0
  6. 06

    提示词里的角色设定有用吗：「你是一位专家」该怎么写才有效（官方文档怎么说）

    提示词开头写「你是一位资深专家」到底有没有用？本文按 Anthropic、OpenAI、Google 官方文档讲清角色设定管什么、不管什么，一句话角色和详细人设各自适合什么场景，角色应该放在哪里，以及比「你是专家」更有效的四个写法。

    ChatGPTClaude0

0 条评论

登录 后参与评论

还没有评论，来抢沙发～