推荐语
Claude Skill 调用率低？可能是你的描述没立对"路标"！掌握这套命名与描述公式，让你的技能命中率飙升90%。
核心内容：
1. Skill 调用失败的根本原因：name与description的"第一印象"不足
2. Claude 选择 Skill 的五步决策机制与典型翻车点
3. 可直接套用的命名公式+避坑清单+模板，打造高触发率"契约"
杨芳贤
53AI创始人/腾讯云(TVP)最具价值专家
很多人做 Skill 的时候，会把时间都花在“正文写得多完整、脚本多强大、流程多复杂”上。结果上线一跑，最扎心的不是能力不够，而是——它根本不被调用。
你明明写了一个能把问题拆到骨头里的代码审查 Skill，可用户随口一句“帮我看看代码”，Claude 反而去调用了另一个看起来没那么强的工具；你的 Skill 只能在角落里安静吃灰。你开始怀疑模型、怀疑机制、怀疑人生。其实，真相往往更朴素：不是它不够聪明，而是你没把“路标”立对。
这篇文章就干一件事：把 Claude Skills 的调用逻辑拆开给你看，然后给你一套可直接套用的命名与 description 写法公式、避坑清单和模板。你写完的 SKILL.md，不只是“说明书”，而是一份能被稳定触发、正确调用的“契约”。
一、同样的 Skill，为何命运不同？
先看两个你可能见过的对比场景：
场景A：
用户随口一句：“帮我看看代码。”
Claude 几乎秒触发某个 Skill，命中率能到 90%。它知道该怎么问、怎么跑流程、怎么输出，像肌肉记忆一样自然。
场景B：
你做的 Skill 功能更强：能查性能瓶颈、能定位内存泄漏、能做重构建议，还能自动生成改动 patch。
但实际命中率只有 30%，甚至出现更尴尬的情况：
很多人会下意识把问题归咎于模型“理解不到位”。但真正的核心往往是：你给它看的第一眼信息，根本不够让它做出正确选择。
你可以把 Skill 想象成商场里的店铺：
招牌写得含糊，店里装修再豪华也没人进；招牌写得像广告，路过的人也只会当作噪音。
尤其关键的是：决定生死的往往不是正文，而是最前面的几十到一百来个 token——name 与 description。很多人把 90% 精力花在正文与脚本，却忽略了这件事。
二、Claude 选择 Skill 的“五步走”（从发现到执行）
你要写出“能被正确调用”的 SKILL.md，前提是理解它到底怎么被选中。把它拆成五个阶段，你会发现每一步都有“典型翻车点”。
阶段1：发现（Discovery）
Claude 在启动或检索可用 Skill 时，通常先扫“目录结构”和“元数据”：
关键认知：这个阶段很多时候不会加载正文。因为成本高、没必要，它只看“第一印象”。
常见失败点：
阶段2：登记（Registration）
它会把 Skill 的元信息登记成类似“卡片/路由表”：建立关键词与语义索引，便于后面匹配用户意图。
常见失败点：
阶段3：匹配（Matching）——命中率主战场
当用户发来一句自然语言，Claude 会把这句话和各 Skill 的 description 做语义对齐，像召回/意图分类那样去挑“最像的那张卡”。
核心结论：description 不是简介，而是“检索入口 + 触发规则集合”。
几个很实用的提醒：
阶段4：加载（Loading）
只有匹配成功，它才会去读 SKILL.md 正文，包括指令、示例、参数、依赖等。
常见失败点：
阶段5：执行（Execution）
它会按正文步骤行动，必要时调用 scripts，同时处理异常与重试。
常见失败点：
流程不线性：步骤跳来跳去，模型容易漏掉关键动作
没有失败兜底：报错后不知道怎么继续
输出不可复用：没有结构字段，后续步骤无法衔接
小结一句话：
Name 是门牌号，Description 是敲门砖；砖没递对，正文再好也进不去。
三、为什么description决定 90% 的命中率
很多人把 description 当成“简介”，写得像 README 的第一段。结果就是：看起来挺像那么回事，但对触发没有帮助。
更准确的定义应该是：
description = 触发规则 + 使用边界 + 输入输出线索
一个好的描述至少要达成三件事：
1）让模型“想得起”（召回）：它知道这个 Skill 的存在和适用场景
2）让模型“选得对”（精准匹配）：它能在相似 Skill 里做出区分
3）让模型“用得稳”（执行前信心）：它知道需要什么输入、会得到什么输出、有哪些限制
四、高命中率 Skill 的“黄金公式”（可直接套用）
4.1 Name（名称）：短小精悍，动词优先
建议结构：动词 + 名词（可选加场景限定）
反例：
正例：
review-code
generate-sql
analyze-csv
原则：
避免抽象名词、内部黑话
一个名字只承载一个核心能力，不要把多个能力塞进去
4.2 Description（描述）：用“触发条件”驱动命中
你可以直接套下面三种公式，按你的 Skill 类型选一种或组合。
万能公式（强触发版）：
“当用户提到[具体关键词/场景]时，应触发此 Skill 以完成[具体动作]，特别是涉及[特定限制/领域]。”
英文并列增强：Trigger this skill when the user asks to [action] involving [keywords], especially for [context].
公式（边界清晰版）：
公式（多意图覆盖版）：
4.3 关键词策略：从“你怎么想”变成“用户怎么说”
强烈建议你在 description 里显式写出三类关键词：
同义词覆盖也很重要：把术语和口语成对写出来，比如：
“内存泄漏 / 内存占用飙升”
“慢 SQL / 查询很慢 / 数据库卡住”
4.4 进阶：中英混合与否定约束（关掉误触发的门）
中英混合：中文描述后附关键英文术语（提升稳定召回）
例：“处理 PDF 表单填写（Fill PDF forms, extract fields）”
否定约束：明确“不做什么”，减少误调用
例：“不处理图片 OCR 识别任务”
缺参追问：写清楚缺信息时应该问什么
例：“若未提供仓库地址/语言/目标分支，需先追问这些必填项”
五、案例对比：一行 description 如何把命中率从 30% 拉到 90%
改造前（模糊）：
“用于检查代码和帮助修复 bug 的工具。”
问题在哪里？
改造后（精准）：
“当用户要求审查 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]。 典型用户表达：“...” “...” “...”
可选增强块（建议在正文里补齐）：
八、总结
在 Agent 时代，“被看见”比“有能力”更重要。YAML 头信息不是装饰，而是你和 Claude 签订的“调用契约”：它决定你能不能被发现、能不能被选中、能不能被放心使用。
你可以立刻做个小实验：挑一个命中率最低的 Skill，只重写 description，按“触发式公式”加入对象词/动作词/约束词，再做一次命中测试对比。很多时候，你会惊讶地发现：正文一字没改，调用率就上去了。
最后送你一句我非常认同的话： 写好一行描述，胜过十页正文。
粤ICP备14082021号
免费POC，
零成本试错
