很多人做 Skill 的时候，会把时间都花在“正文写得多完整、脚本多强大、流程多复杂”上。结果上线一跑，最扎心的不是能力不够，而是——它根本不被调用。
你明明写了一个能把问题拆到骨头里的代码审查 Skill，可用户随口一句“帮我看看代码”，Claude 反而去调用了另一个看起来没那么强的工具；你的 Skill 只能在角落里安静吃灰。你开始怀疑模型、怀疑机制、怀疑人生。其实，真相往往更朴素：不是它不够聪明，而是你没把“路标”立对。
这篇文章就干一件事：把 Claude Skills 的调用逻辑拆开给你看，然后给你一套可直接套用的命名与 description 写法公式、避坑清单和模板。你写完的 SKILL.md，不只是“说明书”，而是一份能被稳定触发、正确调用的“契约”。
一、同样的 Skill，为何命运不同？
先看两个你可能见过的对比场景：
场景A：
用户随口一句：“帮我看看代码。”
Claude 几乎秒触发某个 Skill，命中率能到 90%。它知道该怎么问、怎么跑流程、怎么输出，像肌肉记忆一样自然。
场景B：
你做的 Skill 功能更强：能查性能瓶颈、能定位内存泄漏、能做重构建议，还能自动生成改动 patch。
但实际命中率只有 30%，甚至出现更尴尬的情况：
用户说了需求却不调用（不触发）
该调用 A，结果叫成 B（误触发）
终于触发了，但不会用：缺参不追问、参数用错、输出一会儿结构化一会儿散文（触发后不会用）
很多人会下意识把问题归咎于模型“理解不到位”。但真正的核心往往是：你给它看的第一眼信息，根本不够让它做出正确选择。
你可以把 Skill 想象成商场里的店铺：
name是门牌号description是店门口那块“你进来能解决什么问题”的招牌
招牌写得含糊，店里装修再豪华也没人进；招牌写得像广告，路过的人也只会当作噪音。
尤其关键的是：决定生死的往往不是正文，而是最前面的几十到一百来个 token——name 与 description。很多人把 90% 精力花在正文与脚本，却忽略了这件事。
二、Claude 选择 Skill 的“五步走”（从发现到执行）
你要写出“能被正确调用”的 SKILL.md，前提是理解它到底怎么被选中。把它拆成五个阶段，你会发现每一步都有“典型翻车点”。
阶段1：发现（Discovery）
Claude 在启动或检索可用 Skill 时，通常先扫“目录结构”和“元数据”：
Skill 文件夹名是否有语义
YAML 头信息里的
name与description写了什么
关键认知：这个阶段很多时候不会加载正文。因为成本高、没必要，它只看“第一印象”。
常见失败点：
Skill 散落在不清晰的目录里
命名像
skill-01、tool_v2_final这种对模型完全没意义的编号用途提示不明显，导致发现阶段就“看不见”
阶段2：登记（Registration）
它会把 Skill 的元信息登记成类似“卡片/路由表”：建立关键词与语义索引，便于后面匹配用户意图。
常见失败点：
把
description写成产品文案：“强大、智能、一站式解决方案”边界不清：什么都能做，等于什么都不擅长
没有触发语义：没有动作词、对象词、约束词，导致索引抓不住重点
阶段3：匹配（Matching）——命中率主战场
当用户发来一句自然语言，Claude 会把这句话和各 Skill 的 description 做语义对齐，像召回/意图分类那样去挑“最像的那张卡”。
核心结论：description 不是简介，而是“检索入口 + 触发规则集合”。
几个很实用的提醒：
描述越泛，权重越低；越具体，命中越稳
写清楚触发词（用户会怎么说）、对象词（要处理什么）、约束词（在什么限制下），匹配权重更高
语言敏感度现实存在：英文语义特征更稳定；中文需要更精准。一个常用策略是“中文主体 + 英文关键术语补强”，提升召回稳定性
阶段4：加载（Loading）
只有匹配成功，它才会去读 SKILL.md 正文，包括指令、示例、参数、依赖等。
常见失败点：
前置条件缺失：到底需要什么输入？从哪里拿？
参数名模糊：同一个概念一会儿叫
project一会儿叫repo返回格式不稳定：让模型“不敢用”，宁愿不调用也不冒险
阶段5：执行（Execution）
它会按正文步骤行动，必要时调用 scripts，同时处理异常与重试。
常见失败点：
流程不线性：步骤跳来跳去，模型容易漏掉关键动作
没有失败兜底：报错后不知道怎么继续
输出不可复用：没有结构字段，后续步骤无法衔接
小结一句话：
Name 是门牌号，Description 是敲门砖；砖没递对，正文再好也进不去。
三、为什么description决定 90% 的命中率
很多人把 description 当成“简介”，写得像 README 的第一段。结果就是：看起来挺像那么回事，但对触发没有帮助。
更准确的定义应该是：
description = 触发规则 + 使用边界 + 输入输出线索
一个好的描述至少要达成三件事：
1）让模型“想得起”（召回）：它知道这个 Skill 的存在和适用场景
2）让模型“选得对”（精准匹配）：它能在相似 Skill 里做出区分
3）让模型“用得稳”（执行前信心）：它知道需要什么输入、会得到什么输出、有哪些限制
四、高命中率 Skill 的“黄金公式”（可直接套用）
4.1 Name（名称）：短小精悍，动词优先
建议结构：动词 + 名词（可选加场景限定）
反例：
my-super-tool（像口号，不像能力）code-helper（太泛，任何编程工具都能叫这个）data-analysis-v2（版本号对匹配没价值）
正例：
review-codegenerate-sqlanalyze-csv
原则：
避免抽象名词、内部黑话
一个名字只承载一个核心能力，不要把多个能力塞进去
4.2 Description（描述）：用“触发条件”驱动命中
你可以直接套下面三种公式，按你的 Skill 类型选一种或组合。
万能公式（强触发版）：
“当用户提到[具体关键词/场景]时，应触发此 Skill 以完成[具体动作]，特别是涉及[特定限制/领域]。”
英文并列增强：Trigger this skill when the user asks to [action] involving [keywords], especially for [context].
公式（边界清晰版）：
“用于[任务]；输入是[参数/数据]；输出为[格式/字段]；不适用于[排除场景]。”
公式（多意图覆盖版）：
“支持以下用户表达：‘…’‘…’‘…’（3-6 句用户原话）。”
4.3 关键词策略：从“你怎么想”变成“用户怎么说”
强烈建议你在 description 里显式写出三类关键词：
业务对象词：订单/发票/合同/接口/日志/SQL/内存泄漏
动作词：审查/排查/优化/生成/转换/对账/导出
约束词：批量/增量/最近7天/按项目/按租户/性能
同义词覆盖也很重要：把术语和口语成对写出来，比如：
“内存泄漏 / 内存占用飙升”
“慢 SQL / 查询很慢 / 数据库卡住”
4.4 进阶：中英混合与否定约束（关掉误触发的门）
中英混合：中文描述后附关键英文术语（提升稳定召回）
例：“处理 PDF 表单填写（Fill PDF forms, extract fields）”
否定约束：明确“不做什么”，减少误调用
例：“不处理图片 OCR 识别任务”
缺参追问：写清楚缺信息时应该问什么
例：“若未提供仓库地址/语言/目标分支，需先追问这些必填项”
五、案例对比：一行 description 如何把命中率从 30% 拉到 90%
改造前（模糊）：
“用于检查代码和帮助修复 bug 的工具。”
问题在哪里？
太宽泛：几乎所有编程相关 Skill 都能这么说
与通用能力冲突：模型会更倾向调用“通用代码助手”
缺少触发场景与边界：到底擅长什么？什么时候用你而不是别的？
改造后（精准）：
“当用户要求审查 Python 代码性能、查找内存泄漏或优化 SQL 查询时触发；专注后端服务代码的深度分析与重构建议。”
收益非常直接：
锁定高权重触发词：Python / 性能 / 内存泄漏 / SQL
约束清晰：后端服务、深度分析与重构建议
降低误召回：不是“所有代码都能看”，而是“这类问题就找我”
六、避坑指南：让 Skill 失效的低级错误清单
描述过长：超过约 200 字，关键信息被稀释，初始扫描成本上升
全是形容词：如“强大/智能/好用”，没有实义动词与名词
忽略文件夹/文件名语义：
skill-01永远不如review-code好理解正文与描述不符：描述说做 A，正文在做 B，加载后会出现认知冲突，输出更容易乱
输入输出不稳定：字段/格式漂移会让模型降低调用意愿，宁愿不用也不想背锅
七、落地模板：可复制的 SKILL.md 骨架
你可以按这个骨架直接写，先把“能被正确调用”解决，再谈正文写多漂亮。
name: description: > 当用户提到[触发关键词/场景]并希望[具体动作]时触发此Skill； 关键词覆盖：[对象词1/对象词2] + [动作词1/动作词2] + [约束词1/约束词2]（可中英混合）； 输入需要：[必填信息A/必填信息B]；输出为：[结构/字段/格式]； 不适用于：[排除场景1/排除场景2]。 典型用户表达：“...” “...” “...”
可选增强块（建议在正文里补齐）：
inputs/outputs：字段、类型、示例值usage：3 步以内流程（触发后怎么做）error handling：失败返回、重试策略、如何提示用户补参
八、总结
在 Agent 时代，“被看见”比“有能力”更重要。YAML 头信息不是装饰，而是你和 Claude 签订的“调用契约”：它决定你能不能被发现、能不能被选中、能不能被放心使用。
你可以立刻做个小实验：挑一个命中率最低的 Skill，只重写 description，按“触发式公式”加入对象词/动作词/约束词，再做一次命中测试对比。很多时候，你会惊讶地发现：正文一字没改，调用率就上去了。
最后送你一句我非常认同的话： 写好一行描述，胜过十页正文。
