我最早写的一个 skill是给团队内部测试流程用的。当时花了整整一个晚上认真写了 SKILL.md塞了好几个参考脚本目录结构也自认为很规范。结果一周后看使用记录除了我自己调试时触发过两次团队里没有一个人真正调用它。问题不是他们不想用而是他们根本不知道这个东西能干什么、什么时候该用、怎么用。后来我在 Claude Code、OpenClaw、Codex 这几个平台上陆续折腾了几十个 skill慢慢总结出一个规律绝大多数 skill 开发者的思路都是错的。大家把 skill 当成普通的程序来写研究语法、研究脚本、研究参数却忽略了 skill 和 agent 协作的真正机制。这次我就把压箱底的东西整理出来围绕“skill 为什么没人调用”这个核心问题讲透 8 条质量标准。不管你是刚接触 AI 技能开发的新手还是已经在为企业内部 agent 写 skill 的从业者这套标准都能帮你避开我踩过的坑。一条一条过。1. 先到点子上你的 skill 为什么进了“冷宫”1.1 不是写上 SKILL.md 就叫 skill很多人对 skill 的理解是“把一组指令和脚本打包成一个文件夹”。这个说法没有错但它掩盖了最重要的机制skill 不是被“启动”的而是被 agent“检索”到的。以 Claude Code 的 skills 机制为例每个 skill 实际上是一个目录核心是 SKILL.md 文件。当用户提出一个新任务时agent 会先根据任务内容做一次语义匹配如果发现某个 skill 的 name、description 与当前任务高度相关才会加载这个 skill 目录下的指令和资源。OpenClaw、Codex 的 skill 机制也大同小异。这意味着什么意味着你的 skill 写完了并不会自动出现在 agent 的视野里。如果 description 写得含糊、触发条件不清晰、指令和实际任务场景对不上agent 的检索环节就已经把你过滤掉了。我见过太多 skill作者花大量时间打磨参考脚本却连 skill 的“门面”——description 都没认真写那结果只有一个技术再强也没人调用。1.2 没人调用的五个典型原因以我观察和自己踩过坑的经验一个 skill 发布后没人用翻来覆去就是下面这五个原因谁也找不到它元数据写得差触发词和用户真实表达对不上。比如 user 说的是“帮我梳理接口测试用例”你的 skill 描述里只写“测试专家”那 agent 大概率匹配不上。谁也看不懂它SKILL.md 写成了论文指令含糊、步骤不清模型加载后不知道该先做什么后做什么。谁也不敢用它没有任何示例输出格式不稳定模型每次生成的结果都不一样下游工具根本没法解析。谁也用不起它依赖一堆外部环境设置步骤繁琐用户装完发现缺这个包、少那个命令直接劝退。谁也不想用它没有版本管理没有回归测试模型升级后行为就“飘”了今天能用明天就废。下面这 8 条标准就是我针对这五个问题逐条打出来的补丁。你认真执行完skill 的调用率一定会有肉眼可见的提升。2. 前三条标准定位、可见性、示例2.1 标准一场景聚焦做“手术刀”而不是“瑞士军刀”我见过很多 skill 的描述长这样“一个强大的多功能 AI 助手帮助用户完成各类任务”。这种描述等于没有描述。为什么因为 agent 的 skill 匹配机制是典型的信息检索它需要把用户当前的任务映射到一个具体、单一、边界清晰的技能上。标准做法是一个 skill 只解决一个具体场景的问题。比如“把网页文章转换为 Markdown 格式并提取核心观点摘要”这就是一个很好的聚焦描述而“网页处理专家”这种就是典型的反面教材。聚焦有两个直接好处第一语义检索的命中率更高。描述里包含“网页”“文章”“Markdown”“摘要”这些具体关键词用户说“帮我把这篇网页整理成 md 格式的笔记”时agent 很容易联想到这个 skill。第二指令空间不会被稀释。模型加载 skill 后上下文窗口是有限的如果 SKILL.md 里同时塞了网页解析、PDF 转换、图片识别、格式排版等七八种能力真正需要的执行步骤反而占不到足够权重效果一定会打折。我自己的经验是写 SKILL.md 之前先强迫自己用一句话说清“这个 skill 在什么场景下解决什么问题”。如果这句话里出现了两个以上的功能动词就得拆分。2.2 标准二元数据是入场券description 要“会说话”这一条其实是标准一的延伸但它太重要了值得单独拿出来讲。skill 的元数据字段就是你给 agent 写的“广告文案”。我在实际项目中总结了一套比较稳妥的 description 写法基本结构是先说意图“当用户需要……时使用”再说目标对象“针对接口定义、需求文档、代码仓库……”。最后说动作“生成测试用例、整理代码评审意见、提取错误定位信息……”。举个例子。我写过一个代码评审 skill第一版 description 写的是“代码质量审查助手”结果怎么都匹配不上。改成下面这段之后调用率立刻上来了当用户需要审查某个 Pull Request 或代码变更、查找潜在 Bug、评估代码风格与性能隐患、生成评审意见时使用。支持从本地 Git 仓库或代码片段中获取内容输出按严重程度分级的评审报告。核心在于“当用户需要……时使用”这个句式。它是在模拟 agent 内部检索时的思考过程用户在说“帮我看看这次提交有没有问题”agent 会自己评估这个任务跟哪个 skill 的 description 最接近。你只有把用户可能的话术都放进 description 里它才能“看见”你。2.3 标准三示例驱动让模型“抄作业”而不是“蒙题”这条标准是新手最容易忽略的。很多人写 SKILL.md 时把重点放在“步骤说明”上觉得只要把操作步骤写清楚就行。但大语言模型的强项是模式匹配而不是逻辑推理。它面对一段“按以下步骤操作”的指令执行效果远不如面对“这里有几个输入输出样例你照着这个模式做”。给 skill 写示例我建议至少包含三组标准输入与标准输出最常见的场景输入什么输出什么让模型建立基本范式。带边界的输入与输出比如输入内容很简短、缺少关键字段时模型应该如何处理。失败输入的输出比如文件不存在、API 返回 500 时模型应该报告什么、不应该编造什么。这里有一个关键细节示例要放在 SKILL.md 里最容易被模型读取的位置不要放在单独的 examples 目录里让模型“自行查看”。agent 加载 skill 时SKILL.md 是必读内容而子目录是“按需读取”。如果你的示例需要模型额外翻文件才看得到那模型大概率不会主动去翻。好的做法是把核心示例直接嵌在 SKILL.md 的指令流程之后让模型在理解任务的同时就能看到范式。3. 中间三条标准协议、容错、触发3.1 标准四输入输出协议要收敛别让模型自由发挥我踩过一个很典型的坑。早期写一个“测试用例生成”skill没有规定输出格式结果模型有时候给我 Markdown 表格有时候又输出 JSON还有一次直接在回答里夹带了一段解释文字。下游解析脚本全军覆没我不得不手动清理。从那以后我给所有 skill 定了两条铁律输入必须有明确的变量定义。如果 skill 需要接收参数比如文件路径、接口地址、需求文档内容要在 SKILL.md 开头用明确的变量或 JSON 结构定义清楚并且说明每个字段的格式和必填性。输出必须有固定的结构模板。能用 JSON Schema 就用 JSON Schema不能用的话至少给出一个标准的 Markdown 模板告诉模型“严格按这个结构输出不要自行增删章节”。为什么这个这么重要因为 skill 本质上是让 agent 具备可复用的能力如果每次输出格式都不一样这个能力就不可被下游工具消费。说得直白一点一个不可解析输出的 skill跟一个没法自动化的手工流程没有区别。3.2 标准五失败路径要写在指令里而不是让模型临场发挥大语言模型的“幻觉”是众所周知的而技能执行场景恰恰是把幻觉风险放大的场景。当模型执行 skill 中途遇到错误比如读取文件失败、外部工具没响应、数据格式不对它会倾向于“编一个结果”来完成任务而不是诚实地报告失败。所以一条非常实用的经验是在你的 SKILL.md 里必须明确写上一个“错误处理”小节并且逐条列出“遇到 XX 情况应该怎样处理”。我给内部团队写过一个规范模板错误处理如果输入文件不存在不要生成任何输出直接报告“无法找到指定文件”并列出你尝试过的路径。如果外部 API 请求失败重试一次第二次仍失败则报告错误码和时间戳禁止编造接口返回结果。如果输入信息不足以完成任务列出缺少的字段并给出建议的补充来源不要自行推断。写进指令并配上示例模型执行时就会多一分“安全感”——它知道自己遇到什么情况该走什么分支不用靠猜。3.3 标准六自动化触发条件要精准别做“乱入”的 skill我见过一种 skill触发词的覆盖面太广用户只要提到“文档”两个字它就自动蹦出来结果在编程任务的对话里频繁误触发白白浪费上下文 token用户烦透了最后直接把 skill 禁用了。触发条件的设计是个平衡活。我自己的经验是宁可触发窄一点也不要宽到误伤。一个 skill 的适用场景可以在 description 里写成一句话但触发条件要能识别“用户意图 目标对象”两个维度。比如“需求文档生成测试用例”这个 skilldescription 里触发条件写作“当用户基于需求文档/用户故事生成测试用例时使用”而不是“当用户提到测试时使用”。前者要求语义双重匹配后者则任何跟测试沾边的任务都会中招。另外SKILL.md 开头最好加一段“When to use / When NOT to use”明确告诉模型在哪些情况下不要调用这个 skill。这个办法能极大降低误触发率尤其是当一个项目里同时挂了一堆 skill 的时候。4. 最后两条标准可测试性、生态兼容4.1 标准七可测试、可回归、可迭代这一点是很多独立开发者容易忽略的。大家写完 skill 就发布做没做测试全靠感觉。问题是agent 的底层模型每升级一次同样的 SKILL.md 可能就会产生完全不同的行为。你上周好用的 skill这周可能就“哑”了。我的做法是给每个 skill 建一个测试集通常包含 5 到 10 个标准测试用例。每个测试用例是一组“输入 期望输出特征”我不要求输出逐字一致但要验证核心结构是否稳定。比如测试用例生成的 skill我期望它每次输出都包含“前置条件、测试步骤、预期结果”三要素如果某次输出缺失了“前置条件”回归测试就报警了。这些都是手工验证吗不一定有条件的话可以把测试集通过脚本跑起来批量丢给 agent 处理再自动检查输出是否覆盖了必需字段。没有自动化的精力也要至少做到“每次模型升级后手动跑三五个用例”。否则你的 skill 就会慢慢变成一个“不知道什么时候能用、什么时候不能用”的黑盒用户自然就流失了。4.2 标准八分发与生态体验发布只是开始最后一条非常现实哪怕你的 skill 写得再完美如果安装步骤要三步以上或者只支持某一个特定平台那愿意用它的人就会呈指数级减少。现在 Claude Code、OpenClaw、Codex 这些平台的 skill 机制大同小异核心都是“一个目录 SKILL.md”所以在设计目录结构的时候就应该直接按跨平台方向去考虑。以我的习惯一个标准化 skill 的目录大致是这样的skill-name/ ├── SKILL.md ├── README.md ├── examples/ │ ├── basic-input.md │ └── basic-output.md ├── scripts/ │ └── helper.py └── tests/ ├── case-01.json └── case-02.jsonSKILL.md 是给 agent 看的指令入口README 是给人看的说明文档包括安装方式、适用场景、变更记录scripts 放辅助脚本examples 放可选的更多示例tests 放回归测试数据。发布时至少要在 README 中明示四点支持哪些平台、最低模型版本要求、依赖了哪些外部服务或密钥、更新维护策略。很多 skill 无人问津说白了就是用户担心“装完能不能跑起来、坏了有没有人管”。把这两点回答清楚你的 skill 可信度会立刻上一个台阶。5. 实操复盘把一个失败 skill 改造成可用 skill5.1 反面教材我的“测试用例生成 skill”第一版拿我上面反复提到的那个 skill 举例。第一版的结构是这样的# 测试用例生成助手 当用户需要生成测试用例时使用这个技能。支持各类测试场景提供全面的测试用例覆盖。 ## 步骤 1. 分析用户需求。 2. 根据需求列举测试场景。 3. 为每个场景编写测试用例。 4. 输出测试用例。看起来没问题实际上问题一大堆。description 没有写清楚触发场景步骤里充满了“分析”“理解”“全面”“各类”这类无法被模型落地的模糊词没有规定输出格式没有示例没有错误处理。结果就是agent 偶尔匹配到它就算匹配到了输出质量也忽高忽低更多时候agent 干脆忽略它自己直接用通用能力生成测试用例——效果反而还更稳定一点。5.2 按 8 条标准改造后的第二版后来我按前面说的标准重写了一遍。先聚焦场景把描述改成当用户需要根据需求文档、用户故事或接口定义生成端到端测试用例时使用。擅长梳理正常流程、异常流程、边界条件输出包含前置条件、测试步骤、预期结果的用例清单。然后我在 SKILL.md 里定义了输入 JSON 结构要求模型先提取用户提供的需求标题、需求描述、验收标准如果缺失就列出待补充项。紧接着嵌入了一组示例包含一个标准需求、一个有边界条件的输入、一个信息缺失的输入每种情况都给了对应的输出结构。最后加上了错误处理小节明确禁止模型在输入信息不足时自行编造需求。改造完成后我找团队里三位同事各跑了 10 个真实的测试任务成功率从原来的不到 30% 提升到了 80% 以上。更重要的是输出格式终于稳定了下游可以直接把结果导入测试管理平台。5.3 这中间最值钱的一步回归验证那次改造给我最大的启发不是“指令写细一点”这种常识而是不要一个人在编辑器里闭门造车。我每改一版 SKILL.md就把同样一组测试任务丢给它跑看输出差异。第一版输出五花八门第二版开始收敛第三版基本稳定。这个过程不是靠一次修改完成的而是靠“改—跑—对比—再改”的循环磨出来的。所以如果你现在写的 skill 也面临“没人调用”的问题我的建议是别急着找推广渠道先拿 10 个真实任务回归测一轮把稳定性问题解决掉再谈分发。6. 踩坑实录与上线前自检清单6.1 我踩过的五个坑请直接避让以下坑位都是我在真实项目里用时间换来的坑一SKILL.md 写成长篇小说。第一次写 skill 时我把所有执行细节都塞进 SKILL.md结果超过 800 行模型读到后面注意力涣散反而比短指令效果更差。现在我的经验是核心流程控制在 300 行以内更细节的参考资料放子目录按需读取SKILL.md 只是“索引 主线流程”而不是“全部知识的集合”。坑二在 description 里堆砌抽象形容词。“强大的”“智能的”“全面的”“高效的”——这些词看起来是夸你的 skill但对语义检索毫无帮助甚至会稀释真正有用的关键词。用动词和名词描述能力不要用形容词。坑三忽略“何时不该用”。很多 skill 只写了“什么时候用”没写“什么时候不用”导致模型在无关场景下误加载、误输出。加了 When NOT to use 之后误触发率肉眼可见地下降。坑四依赖未说明的外部资源。比如 skill 依赖某个 Python 包但没在 README 里写清楚或者依赖某个环境变量但没给出配置示例。用户一跑就报错直接删除。坑五不做版本管理。Agent 升级后 skill 行为变了你不知道用户发现了反馈你才知道。最佳实践是在 SKILL.md 顶部记录 skill 版本号和兼容的模型版本每次修改都更新 changelog。6.2 上线前自检清单一个 skill 值不值得发布发布任何一个 skill 之前我个人都会过一次下面的自检表。如果有一项不通过就不发布先回去改检查项对应的标准自检问题1场景聚焦这个 skill 是否只解决一个核心场景问题一句话能不能说清它的价值2元数据可见性description 是否覆盖了用户可能使用的 3 种以上自然语言表达有没有与任务无关的抽象词3示例驱动SKILL.md 里是否至少嵌入了 3 组“输入—输出”示例是否覆盖边界场景和失败场景4协议收敛输入变量是否定义清晰输出是否有固定模板或 JSON Schema5容错处理遇到文件缺失、API 报错、信息不足时模型是否知道“该怎么办”6触发条件是否写了 When to use / When NOT to use误触发风险能否接受7可测试性是否准备了一组回归测试用例模型升级后能否快速验证行为变化8生态体验在不同平台Claude Code / OpenClaw / Codex 等上能否直接复制使用README 是否说明了依赖和更新策略这张表看起来像“流程管理”但我保证每次发布前认真过一遍能帮你省掉大量用户的吐槽和售后问题。最后再分享一个我个人的习惯写完一个 skill不要急着发给别人先自己在真实工作流里用一周。观察它在不刻意提醒的情况下agent 到底会不会主动加载它观察它生成的结果是不是真的比通用能力更省事。如果连你自己都懒得用它那它就不该上线。真正的质量标准不是在文档里写出来的而是在一次次“没人调用—排查原因—动手重构—再次验证”的循环里磨出来的。希望这 8 条标准能帮你少走我走过的那些弯路。