最近在帮团队review一批新提交的Claude Code skill现象很有意思每个skill单独看都能跑示例输出也有模有样但一放进真实项目就开始“作妖”——有的触发时机完全不对有的输出跟需求对不上有的跑一次烧掉大量上下文还有的遇到异常就直接摆烂。反复踩了几次坑之后我慢慢磨出了一套skill验收方法前前后后就用五个问题来测我管它叫“设计五问法”。这套方法本来是给自己验收用的后来发现用来指导skill开发也特别顺手干脆整理出来分享给正在写或者正在批量收skill的人尤其是那种准备上到生产环境、要给团队或者客户用的商用级skill。先说清楚一个判断市面上大多数被吐槽“不好用”的skill不是模型能力不行而是设计阶段没人对质量负责。写的人觉得“能让AI跑通就行”用的人却需要“在任何情况下都稳定输出正确结果”。商用级和能跑中间隔着的是职责边界、输入契约、输出质量、异常兜底、成本控制这五道关。下面我挨个拆开讲。1. 为什么 skill 会“表面可用一用就翻车”1.1 从三个翻车现场说起我见过一个典型翻车团队做了一个“日报生成”skill写完自测了几次生成出来的日报格式漂亮、语句通顺就高高兴兴提交了。结果上线一周真正被触发成功的次数一只手数得过来。原因很简单这个skill的description写的是“帮助你生成日报和周报”听上去没什么问题但问题是它没有写清楚“什么时候该用、什么时候不该用”。于是模型经常在用户明明只需要快速记一条待办事项的时候也去调用它生成一篇1000字的日报反而干扰了用户。另一个翻车更致命。有个“代码重构”skill设计的时候只顾着写“要做什么”和“分几步做”完全没有考虑危险操作的处理。结果模型拿着这个skill兴冲冲地跑了某次遇到一个用户没备份的关键文件它直接原地覆盖改完发现把原本能跑的代码改崩了而且文件还没法恢复。这种事故出一次整个团队对AI工具的信任度就掉一大截。还有一个翻车偏“慢性病”一个摘要总结类的skillbody里塞了将近200行的“好词好句”和“风格参考”每次调用都把这些内容一字不差地灌进上下文。单次看不出来一天被触发几十次之后token消耗肉眼可见地飙升而且因为可用上下文被挤占skill原本该做的总结质量反而下降了。以上三个问题分别对应职责边界、异常兜底、成本控制这三个维度全都不是“能不能跑”层面的问题。1.2 五问法在验收什么基于这些教训我给skill验收设计了两条基本原则。第一条是验收必须发生在真实使用场景里不能只看演示路径第二条是验收标准必须是可以被回答的不能停留在“好不好用”这种主观判断上。于是我把一个skill从“定义”到“运行”再到“收尾”的完整生命周期拆成了五个关键检查点职责边界、输入契约、输出质量、异常兜底、成本控制。每一个检查点对应一个问题五个问题按顺序问完一个skill到底是在裸奔还是能穿去办公心里基本就有数了。这五个问题我相信很多人看完会觉得简单但简单不意味着容易被真正落实。真正的难点在于它要求你在评判一个skill的时候切换掉“功能演示”心态转而用“生产验收”的心态去较真。接下来我逐个展开每个问题都会给出判定标准和验收操作。2. 第一问它真的知道自己该干什么吗2.1 先看三层“门面”一个Claude Code skill从结构上说核心是SKILL.md文件。它通常分三层最上面是name也就是skill的名字接着是description描述这个skill的触发条件和使用场景再往下是body也就是真正指导模型怎么干活的主干内容。这三层里name和description决定了模型“什么时候翻你的牌子”body决定了模型“被翻牌子之后能不能表现好”。先说name商用级skill的name至少要满足一个硬条件——唯一性好认。别起“helper”“tool”“分析”这种撞车率极高的名字尽量用带领域特征的命名比如“project-structure-analyzer”“release-note-generator”这种用户一眼能看懂模型在上下文里匹配时也不容易混。但name只是标识真正决定一个skill能不能被正确触发的是description。我验收一个skill第一步永远是读description而且要带着一个非常功利的问题看完这段描述我能不能准确说出这个skill的触发条件和不适用场景。如果答案是不能那这个description就是不合格的。2.2 边界感不清后果比你想的严重model在Claude Code里是自动判断“要不要调用skill”的判断依据就来自skill的name和description。如果description写得模糊模型就只能“猜”。猜对了算运气好猜错了就会造成两种典型事故。第一种是误触发行为和用户当前请求不符合。比如用户想清理一下临时文件你有一个“文件整理”skill描述里写了“帮助用户管理、清理、整理文件”。模型一看好这是管理文件场景激活它。结果skill的设计初衷是“按分类归档业务文档”根本不该去动临时目录两边的预期错位用户看到的就是AI突然做了一堆多余操作。第二种是漏触发模型该用的时候没用。描述里全是专业黑话模型理解不了“什么时候该用”干脆忽略这样skill再强也是仓库里的一具高级摆设。那怎么判断description“到底写得行不行”我的实操方法是拉一个不看这段代码的人来“盲测”。你把SKILL.md发给他只让他看name和description然后问两个问题第一什么情况下你会想到用这个skill第二什么情况下你绝对不该用。如果这个人和你写的时候设想的答案一致说明边界清晰如果两个人能说出三种完全不同的使用场景那这个描述就是灾难级的模糊。还有一个小技巧description里最好明确写下“不适用场景”。很多Skill作者只写“能做什么”不写“不做什么”。这其实是浪费了一个特别好的边界信息位。比如“release-note-generator”的description里应该明确写一句“本skill不适用于内部开发日志的整理只面向对外发布版本”。多写这一句就能帮模型在相似场景里做出更准的判断。2.3 边界感验收的通过线我给自己定的第一问通过线是三条只看name和description判断“何时用、何时不用”的准确性不低于90%description中没有“万能词”像“帮助用户处理各种文档”“辅助任何分析任务”这种话一票否决body部分没有上下位目标混在一起一个skill只围绕一个核心目标展开。如果里面有“顺便生成图表”“顺便翻译文本”这类支线任务我会要求拆出去另立一个skill。第一问过关之后才进入下一问。输入契约这层恰恰是很多“能用”的skill暴露真实水平的地方。3. 第二问输入契约经得起“乱来”吗3.1 参数是契约不是备注如果说description是skill的门面那输入参数就是skill和调用方模型之间的正式契约。商用级skill一定有一份严谨的输入接口定义。这里的输入既包括直接通过工具调用传入的参数也包括模型在执行过程中从用户对话里获取的信息。我见过很多skill的body里写“请根据用户需求处理”然后就没有然后了参数全靠模型现场现编。这样带来的直接问题就是同一个任务每次跑出来的行为都可能不一样因为你没有给模型一个明确的输入格式约束。今天它能根据上下文猜出你要的文件路径明天换一个上下文它就猜不出来了甚至可能输出一个根本不存在的文件。契约严密的skill在输入部分至少要回答四个问题必填项有哪些、可选项有哪些、每个参数的类型和格式是什么、参数缺失时应该怎么处理。这四个问题不能存在body的“隐藏角落”里更不能靠模型自己悟而是要显式地写清楚。3.2 从“日期格式”看到的重灾区举个例子一个生成周报的skill设计者知道需要用户提供日期范围于是body里写了一句“获取用户要生成的周报时间范围”。这句话看着没问题但放在真实调用场景里就有隐患。用户可能会说“上一周”模型转化成时间参数时有概率出差用户还喜欢说“帮我看看这个月第三周的数据”这种表达不经过训练很容易切片切错。更重要的是你没有规定输出日期格式模型可能给你“2025年6月第3周”也可能给你“2025-06-16到2025-06-20”不同格式会导致下游脚本解析失败。后来我把这个skill的输入部分改成明确的schema必填参数start_date和end_date格式统一为YYYY-MM-DD还有一个可选参数timezone默认值为Asia/Shanghai参数缺失时默认取上周一到上周五并在输出里明确标注“你未指定时间范围我使用了默认的上周一到上周五”。这样改完模型拿到的契约清晰了下游脚本也稳定了。要特别注意给输入参数加默认值不是为了省事而是为了给模型一个“可执行的兜底方案”不至于在参数缺失时瞎编。而“瞎编”恰恰是很多skill踩坑的地方。3.3 脏输入与边缘输入测试第二问的验收操作我通常不会拿正常输入去测而是专门构造“脏数据”和“边缘数据”来“折磨”这个skill。所谓脏输入就是那种格式不对、明显缺字段、或者语义含混的输入边缘输入则是数据为空、只有一个字符、或者数据量大到要超出上下文范围的情况。举几个我常用的测试用例一个报告生成skill给它一个空目录路径看它会不会直接报错还是会明确提示“目录为空无法生成报告请确认路径”一个SQL分析skill把表名故意传错看它能不能识别出“表不存在”并且在输出里给出“请检查表名是否为xx”这类可执行建议一个文档转换skill给它传一个非UTF-8编码的文件看它报错信息是“人类看得懂的话”还是直接把二进制刷到屏幕上。我会建议所有skill设计者在body里就预设好“输入异常情况”的处理逻辑。不要觉得这是在增加复杂度——恰恰相反把异常处理写进契约能在运行时帮你省掉大把人工排查成本。模型碰到异常输入至少要知道“我现在停下来并解释为什么”而不是“硬着头皮继续跑”。验收时如果发现异常输入下模型反复尝试了几种错误办法最后输出一段模棱两可的结果这一问直接不通过。商用环境不允许这种“薛定谔的输出”出现。4. 第三问输出能让人“闭着眼睛用”吗4.1 输出三件套结构化、状态、下一步输入契约解决了“怎么进去”的问题紧接着要解决的是“出来什么”和“出来得怎么样”。一个商用级skill的输出不应该是一段“看起来很有道理”的话而应该满足三个条件结构化、有状态、能指导下一步。先说结构化。所谓结构化就是输出要遵循固定模板要么是明确的JSON/Markdown结构要么是固定的字段顺序。为什么要这样因为商用环境里skill的输出往往不是终点而是流水线上的一个节点下游可能还有脚本在解析有任务在继续执行。输出格式不固定下游就没法接。一个“项目风险分析”skill每次输出的章节名一会儿叫“主要风险”一会儿叫“风险清单”一会儿又叫“潜在问题”那下游做聚合分析时就得天天改匹配逻辑维护成本直线上升。再说有状态。输出里必须能看出“这次调用到底成没成功”。最差的做法是模糊地写“我不确定是否成功”。好一点的做法是老老实实声明“已完成/部分完成/失败”并给出简要原因。我在设计验收标准时要求一个商用级skill输出里至少要有一个能程序判断的“状态字段”比如JSON里的success字段配合一条message说明详情。有了状态外部流程才能决定是继续还是回滚。最后是能指导下一步。很多skill输出的问题在于它有信息没动作——给了一堆分析结果却不告诉使用者“接下来该干什么”。这在需要多步协作的任务里很要命。我通常会要求输出末尾给出一个“建议的下一步操作”小节里面写清楚“如果要继续可以让我做什么如果结果有误应该去检查哪个环节”。4.2 输出好看不等于好用我在验收时经常看见这种情况一个文档审查skill输出特别华丽它用一段专业口吻详细分析了文档里的问题总结了不少于十个“优化建议”结论部分还加了加粗和引用格式。但我照着它的输出去做修改时发现不知道该从哪里下手——因为建议全是对策性描述没有一条直接给出“可以替换的文案”也没有说明修改后会带来什么影响。这就是典型的好看不好用。它的输出适合“汇报”不适合“交付”。商用级skill不应该给你一篇“论文”而应该给你一个“交付物”能落地的文案、能执行的命令、能解析的结构化数据。为了强化这一点我给自己所有skill都定了一条规矩输出里必须包含可直接复制使用的产物如果产物是文字就直接给出改写后的目标内容如果产物是代码或命令就要给出完整的、可以粘贴运行的版本。4.3 输出验收的“信噪比”检查第三问的验收我用一个简单但特别有效的方法让一个没用过这个skill的人只看输出不看任何辅助说明直接照着执行下一步。如果对方能在五分钟内完成“理解结果并执行下一步”说明输出质量过关如果对方需要反反复复问你好几遍“所以这个报告是成功还是失败”“那我应该改哪里”那就是输出端的信息熵太高不合格。另外还要检查输出内容的“信噪比”。模型天然喜欢写长文本、加解释、补背景但商用skill的输出在信息密度上要的是克制。该直接给发布命令就不要在中间夹两句“为了确保发布流程的顺利我们建议……”。一个好的做法是结构上做到状态头、正文数据表、明确的下一步动作这三段式把解释性内容压缩到最少。5. 第四问出错的时候它会“体面退场”吗5.1 四个必测的异常场景前三个问题覆盖的是skill的“正常路径”但真正拉开普通skill和商用级skill差距的是异常路径上的表现。我复盘过自己碰到的各种线上问题总结了四个必测异常场景建议每个skill都拿这四个场景过一遍。第一个是文件或资源缺失。skill依赖的文件不存在、目录被移动、数据库表被删这时候它能不能正确感知并给出现状说明第二个是权限不足。读一个不可读的目录、写一个不可写的路径、执行一个没有执行权限的脚本它是直接报一个系统级错误还是会用白话告诉用户“当前没有权限请确认xx目录的访问权限”第三个是依赖服务不可用。比如skill要调用外部接口接口超时或返回500它是傻等还是快速失败并给出替代方案第四个是参数非法。上一问提过就是那种明显传错、传空、传了不支持格式的参数它能不能接住而不是乱跑。这四类异常任何一个能在“不炸掉当前对话上下文、不伤害已有数据”的前提下被准确识别并给出可执行提示我就在第四问上给这个skill合格。5.2 失败时至少要给出什么为了方便记忆我把失败输出的最低标准总结为“三件套”错误信息、原因分析、修复动作。一个skill出错时输出里必须包含这三样东西缺一样都算不合格。错误信息要说得是“人话”不是一长串堆栈或者“文件读取异常”这种冷冰冰的技术话术而是有方向感的描述比如“无法读取配置文件config.yaml请检查文件是否存在或路径是否错误”。原因分析要简短直接明确告诉用户“问题出在哪个环节”而不是“系统内部错误”这种甩锅话。修复动作最关键要给出用户可以立刻执行的选项比如“可以尝试运行xx命令检查当前环境或者将文件路径改为xx后重试”。很多skill在异常场景下的典型表现是模型开始“脑补”。它读不到文件内容但会基于文件名和经验假设内容继续执行最后产出一份基于错误信息的分析报告。这种“坏数据好包装”的反馈是商用环境里最危险的行为必须坚决杜绝。我自己的做法是在skill body里写死一条指令当任何步骤出现异常时严禁推测立刻停止并输出问题三件套。5.3 破坏性操作防护体系第四问里还有一个隐形考点破坏性操作。不少skill设计时一心想着完成功能完全没想过它正在操作的东西“不能随便动”。我把破坏性操作的防护体系分成三级。第一级是操作前必须dry-run。凡是涉及到覆盖文件、删除数据、修改配置这类有持久性影响的操作必须默认先跑只看不做并且把即将产生的改动清单展示出来。第二级是确认机制。dry-run结果展示给用户后要明确询问“是否确认执行”得到正向确认才能继续。第三级是留下退路。如果是文件类操作在执行前先把原文件复制成带时间戳的备份再动手如果是命令类操作尽量提供回滚方案。这套防护体系写进skill body不单单是防模型“手滑”也是在给用户留出自查的窗口。商用环境里一次误操作损失的可能不是一段代码而是一整套流水线的信任。我用这套三级防护标准验收下来的经验是能老老实实做dry-run和备份的skill在真实生产里翻车率要低一个量级。5.4 把正常路径“改坏”来测试第四问的验收操作听起来有点“自虐”我会故意把一个skill运行环境中能正常工作的环节改坏然后看它的表现。比如把一个临时目录的权限改成不可读再触发一个分析skill或者把一个依赖脚本的名字改成不存在的再触发一个批量处理skill。重点观察三个方面第一它会不会停下来并报告错误第二它给出的错误信息是否包含完整的“问题三件套”第三在错误发生后它会不会因为尝试继续操作而把原有数据搞得更糟。这三条只要有一条不行第四问就不通过。测试异常路径花的时间通常比测试正常路径长但这是我最舍不得省的一步——因为线上事故几乎都发生在正常路径之外。6. 第五问它会不会闷声烧光你的token6.1 三个成本刺客token成本是商用级skill最容易被人忽略的一环因为它在功能演示时完全看不出来只有进入高频率调用阶段才会爆发。我总结过skill的三个隐藏成本点每一个都是实打实的“成本刺客”。第一个是description太长。每次对话时模型都需要根据所有已装配skill的name和description来决定是否触发。如果一个skill的description有500字你装了30个类似的skill光这一轮的“翻牌决策”就要消耗上万token。这里有一个特别容易被忽视的公式一个skill的description在每次对话中消耗的token description长度 × 对话轮数。所以description不是写得越详细越好而是应该在“信息完整”和“长度克制”之间取平衡。第二个是body内容太长且频繁被加载。skill一旦被触发它的完整body会进入当前对话上下文。如果body里塞了大量参考示例、背景介绍、FAQ每次触发都是一笔不小的消耗。我见过最夸张的一个skillbody将近12000字每次调用都会被原原本本吃进去。相比之下把静态参考材料放到resources目录下在需要时按需读取成本能降一个数量级。第三个是skill内部脚本反复读取大文件。有些skill为了求稳会在脚本里把一个大目录里的所有文件都扫描一遍每次调用都读读完还不缓存在上下文之外。这个看似不起眼的设计在高频调用下会造成巨大的时间延迟和token开支。所以我会检查skill的scripts看它是否做了最小化读取能不能利用路径过滤只读取目标文件。6.2 成本测量和预算线的计算成本不能靠“感觉”要有一个可计算的测量方法。我给自己的测量步骤是同一个任务同一份输入让skill跑一次完整流程查看本轮调用的总token数以及其中有多少是固定开销比如description和body带来的输入token将固定开销×预期日均调用次数就能估算出这个skill的“固定日成本”。举个例子。一个日报生成skill参数和对话输入共消耗2000 token但skill本身description加body一共消耗8000 token所以单次调用总消耗10000 token左右。如果日均被调用50次那一天的固定消耗就是50×800040万token。按模型价格折算这部分成本已经不可忽略。这时候你就会发现body里多写的那些“详细注释”和“参考案例”其实都被转化成了真金白银。我一般会给商用级skill定两条预算线一条是描述区预算线name加description的总长度建议控制在800到1200字以内另一条是触发生效预算线一个skill的body长度建议在3000字以内超过这个量就要认真考虑是不是把一部分静态内容外置到resources目录去。当然这两个数字不是绝对标准具体要根据模型上下文大小和调用频率调整但方向是对的能少灌进上下文的就不要灌进去。6.3 成本验收操作模拟一次真实调用第五问的验收操作就是真实调用一次观察上下文账单。我会记录三个数据skill被加载前的上下文长度、skill被加载后的上下文长度、任务完成后的总token消耗。前后差值就是skill的“加载开销”。商用量里还有一个很容易忽略的坑同一个对话里模型有时会多次加载同一个skill。比如开了自动刷新上下文的功能模型需要重读skill来确认“下一步如何执行”这时候加载开销就会翻倍。我实测过一些设计不合理的skill单次任务里skill被连续加载了三遍光这一项的token消耗就比任务本身还高。这种问题光看单次调用往往发现不了需要专门记录“上下文加载轨迹”。最直接的解决方式就是把需要反复用到的、逻辑性的指令尽量提到body最前面让模型只读一次就能抓住主流程不要东一句西一句逼着模型来回翻。我看一个skill的“成本画像”是否合格标准是加载开销占单次调用总token的比例不超过30%。超过这个比例说明这个skill的信息组织方式有问题输出还没有加载开销大整体性价比太低要先优化成本再上线。7. 把五问做成一张验收清单7.1 五问打分表五问讲完了但真正落地使用的时候你不可能每次都在脑子里现过流程。我建议做一张表直接平铺成验收清单谁拿到都能用。我自己的版本大概长这样贴出来给大家参考验收问题核心验收动作过线标准常见失败信号第一问职责清晰吗盲读name和description判断触发与不适用场景只看描述判断“何时用何时不用”准确率90%以上description用“各种”“辅助”等万能词没有不适用场景说明第二问输入有契约吗构造脏输入和边缘输入测试异常输入时能稳定给出提示或兜底默认值不瞎猜参数靠模型脑补缺参时直接取到离谱值日期格式不统一第三问输出能直接落地吗让新人只看输出执行下一步五分钟内能理解结果并执行下一步输出只有分析没有动作状态不明格式每次不固定第四问异常会体面退场吗改坏运行环境观察失败表现失败时输出“错误原因修复动作”不破坏已有数据遇到异常继续脑补错误信息是“天书”操作前无确认第五问成本可控吗记录一次真实调用的token账单加载开销占比不超过单次调用总token的30%description或body超长重复加载脚本反复读无关大文件7.2 严重度分级和整改顺序五问里每一问都重要但真到了整改阶段资源有限不可能全量重写。我一般先按严重程度分三档P0是会造成数据资产安全或者服务不可用的比如第四问里遇到异常继续执行、有破坏性操作却不做备份P1是会造成输出质量不稳定、加重维护负担的比如第三问输出不结构化、第二问输入契约含糊P2是成本或体验层面的问题比如第五问的过度加载、第一问的边界模糊。整改顺序上我个人的经验是先修P0再花时间磨P2最后回头优化P1。原因很朴素P0问题会出事故P1问题会让用户拒绝使用而P2问题往往是skill设计者有兴趣去做成本优化的地方——它不直接造成用户拒绝但会决定这个skill能否长期留存使用。不过对一个已经上线的商用级skill我不会等到发布后再看它踩中第四问而是在验收时就把这几个等级卡死。这里顺带提一个很多初次接触skill的人会混淆的概念skill和agent的区别。简单说agent更像一个自主决策的“执行者”它会接收任务、拆解计划、调度工具、持续循环直到完成而skill更像是给模型“装配的一项专项能力”它不会主导对话只是在特定场景下被“召之即来挥之即去”。设计五问法主要针对的是skill这种“专项能力包”agent的质量标准会更复杂因为涉及任务规划、记忆管理和子任务调度但五问里关于输入契约和输出质量的思路对agent的子模块同样适用。7.3 避坑经验命名规范和团队协作最后再补充几条我踩过坑之后总结出的团队协作经验。第一skill命名要全球唯一且语义明确。如果一个团队里同时有“file-organizer”和“file-helper”模型几乎必然出错。我现在的做法是团队内部用“产品线-功能-动词”的命名格式比如“data-pipeline-validator”。命名规范这件事花一小时定好后面能省十小时的排查时间。第二skill的版本要记录在案。我见过不少团队skill的SKILL.md在群里传来传去改了什么全靠个人记忆最后谁也说不清当前生效的到底是哪个版本。现在我会在SKILL.md的frontmatter里加上version字段并在变更历史记录文件里写明更新日志。这个看起来“非功能”的细节在回溯问题时帮过大忙。第三多嘴提一句测试每次改动skill之后至少完整跑一遍“三问自测”也就是边界测试、异常测试、成本测试。不追求每版都完美但基础的回归要守住。商用级skill最怕的不是功能少而是“你不知道它在线上会变成什么样”。版本记录和回归测试就是把这层不确定性压下去的两个抓手。我自己现在的新习惯是把完整版“五问验收清单”直接内置到团队模板仓库里任何新skill提交前设计者自己先按表格跑一遍附上每问的测试结果再进入人工review。从这几周的效果来看光是“自己先测一遍”这一个动作就把很大一部分低质量skill挡在了大门外review的效率也肉眼可见地高了很多。如果你也正在搭建团队的skill体系可以直接拿这张表去用五个问题过完哪些能上线哪些需要回炉重造基本一目了然。
