1. 从能跑到敢上线Skill 质量的三道门槛写 Skill 这件事门槛其实比大多数人想象的要低。一个SKILL.md加几个脚本跑通一次 Demo看起来就成了。但我自己踩过的坑告诉我能跑通的 Skill 和能上线的 Skill中间隔着的不是一行代码而是一整套质量意识。这个系列的前两篇聊了 Skill 是什么、怎么搭骨架这一篇专门讲最难也最容易被跳过的一段——怎么把它写好、测好最后安全地推上线。先把话说在前面Skill 的本质是给 Agent 用的一份可执行说明书。它和普通函数库最大的区别在于调用方不是人而是一个会自由发挥的模型。这意味着你的 Skill 面对的不是确定的输入输出而是一堆模型可能这么理解、也可能那么理解的模糊地带。所以写 Skill 的第一原则不是功能多强而是边界多清晰。我把 Skill 的质量分成三道门槛按顺序过第一道可读性门槛。SKILL.md是给模型读的也是给未来的自己读的。描述含糊、触发条件模糊的 Skill模型要么不调用要么乱调用。第二道可测性门槛。没有测试的 Skill 等于没有 Skill。你需要一套能复现、能回归、能覆盖边界情况的测试方法。第三道可上线门槛。上线不是发个版本这么简单涉及权限、错误处理、回滚、监控任何一环缺失都可能让一个实验室玩具在生产环境翻车。这三道门槛对应本文的三个核心章节最后再加一节讲上线后的持续维护。整套流程走下来一个 Skill 才算真正毕业。下面逐层拆。2. 写好 SKILL.md让模型一眼看懂、一次调对2.1 触发描述是 Skill 的命门不是装饰很多人写SKILL.md把 90% 的精力花在正文步骤上触发描述description / when to use随便写两句。这是本末倒置。模型决定要不要调用你的 Skill几乎完全依赖触发描述这一段。正文写得再漂亮模型压根没触发等于零。我见过最典型的反例是这样写的description: 处理数据这句话的问题在于它既没说处理什么数据也没说什么时候该用。模型看到处理数据这四个字面对一个 CSV 清洗任务时可能触发面对一个日志分析任务时也可能触发最后要么误触发、要么该触发时不触发。正确的写法应该包含三个要素做什么、什么场景用、什么场景别用。举个例子description: 将结构化的 CSV/TSV 表格数据做清洗与规范化 包括去重、缺失值填充、列类型推断、日期格式统一。 适用于用户提供了表格文件且需要标准化输出的场景。 不适用于非结构化文本、图片或需要联网抓取的场景。注意最后那句不适用于……。负向边界和正向描述一样重要它直接降低了误触发率。模型在多个 Skill 之间做选择时明确的排除条件能帮它快速收敛。提示触发描述里尽量用用户会怎么描述这个需求的自然语言而不是内部术语。模型匹配的是语义不是关键词表。2.2 正文结构把隐性知识翻译成显性步骤SKILL.md的正文本质是把一个熟练工脑子里的隐性流程翻译成模型能照着做的显性步骤。这里有个反直觉的经验步骤不是越细越好而是要细到模型不会自由发挥粗到模型能灵活应对。太粗的例子读取文件清洗数据输出结果。——模型会自己脑补清洗规则结果不可控。太细的例子把每一行 pandas 代码都写进去——模型变成了代码复读机遇到稍微不同的输入就卡死。我的经验是采用意图 约束 示例的三段式意图这一步要达成什么目标一句话。约束必须遵守的规则、边界、禁止事项。示例一个输入输出的具体样例让模型对齐预期。举个清洗 Skill 的片段## 步骤 2列类型推断 目标为每一列推断最合适的数据类型。 约束 - 若某列 90% 以上值可解析为数字判定为数值列。 - 日期列必须统一为 ISO 8601 格式YYYY-MM-DD。 - 无法判定的列保持字符串类型不要猜测。 示例 输入列 [1, 2, 3, N/A] → 数值列缺失值记为 null 输入列 [2024/1/5, 2024-01-06] → 日期列统一为 2024-01-05, 2024-01-06这种写法让模型既有明确的目标又有可参照的样例遇到边界情况时不会乱来。2.3 参数与返回值契约要写死别留给模型猜Skill 如果带参数参数定义就是一份契约。契约模糊模型传参就会五花八门。我坚持两个原则每个参数都要有类型、是否必填、取值范围、默认值。返回值要说明结构尤其是错误情况返回什么。用表格把参数列清楚比一大段文字描述有效得多参数名类型必填说明默认值input_pathstring是待清洗文件的绝对路径无dedupboolean否是否去重truefill_strategyenum否缺失值策略drop/mean/zerodropdate_formatstring否目标日期格式YYYY-MM-DD返回值同样要写清楚成功和失败两种形态。失败时返回结构化错误而不是抛一个裸异常这样 Agent 才有机会根据错误信息自我修正或向用户求助。2.4 一个常被忽略的细节Skill 的人格Skill 写多了你会发现每个 Skill 其实有自己的人格——有的激进自动做很多决策有的保守遇到不确定就停下来问。这个人格要在SKILL.md里明确表达出来否则模型会用自己的默认风格去填补空白。比如一个涉及删除操作的 Skill我会在开头就写死## 行为准则 - 任何删除、覆盖操作前必须先输出将要影响的对象清单并等待确认。 - 遇到无法判断的情况停止并询问不要自行假设。 - 所有写操作默认在副本上进行保留原始文件。这几句话看似简单但它决定了 Skill 上线后是省心还是闯祸。保守的 Skill 上线后最多是效率低一点激进的 Skill 上线后可能直接删库。这个取舍在写SKILL.md的时候就要定下来。3. 测好 Skill一套能复现、能回归的验证方法3.1 为什么 Skill 的测试和普通代码测试不一样普通代码测试输入确定、输出确定断言写死就行。Skill 的测试难在中间隔了一个模型同样的输入模型可能走不同的路径输出措辞也可能不同。所以 Skill 的测试不能只测输出字符串相等而要测行为是否达成目标。我把 Skill 测试分成三个层次从易到难单元层测 Skill 依赖的脚本、函数。这部分和普通代码测试一样用 pytest 之类直接断言。行为层测 Skill 被调用后是否完成了预期动作文件是否生成、数据是否正确、格式是否合规。语义层测模型对 Skill 的理解是否正确该触发时触发、不该触发时不触发、参数传对。单元层最好写语义层最难写但恰恰是语义层决定了 Skill 的可用性。3.2 单元层把脚本从 Skill 里抠出来单独测一个健康的 Skill逻辑应该尽量下沉到独立脚本里SKILL.md只负责编排。这样脚本可以脱离模型单独测试。比如清洗逻辑写成一个clean.py测试就变成普通的函数测试import pytest from clean import infer_column_type, dedup_rows def test_infer_numeric_column(): assert infer_column_type([1, 2, 3, N/A]) numeric def test_infer_date_column(): assert infer_column_type([2024/1/5, 2024-01-06]) date def test_dedup_keeps_first(): rows [{id: 1}, {id: 1}, {id: 2}] assert len(dedup_rows(rows)) 2这一步的价值在于当 Skill 行为异常时你能快速定位是脚本 bug 还是模型理解偏差。如果脚本测试全绿那问题一定出在SKILL.md的描述或模型的执行上。3.3 行为层用固定样例做端到端回归行为层测试的核心是准备一批输入-期望输出的样例每次改动 Skill 后跑一遍看行为是否退化。样例要覆盖正常路径标准输入期望标准输出。边界情况空文件、单行、超大文件、全缺失值。异常输入格式错误、编码错误、权限不足。我习惯把样例组织成一个目录每个样例一个文件夹里面放input和expectedtests/ case_normal/ input.csv expected.csv case_empty/ input.csv expected.csv case_bad_encoding/ input.csv expected_error.txt跑测试时让 Agent 对每个input执行 Skill然后把结果和expected对比。对比不要求逐字节相等模型输出可能有措辞差异而是对比关键字段和结构。这一步能抓住绝大多数回归问题。3.4 语义层触发准确率和参数正确率怎么测语义层测试最容易被跳过但它直接关系到 Skill 会不会该用不用、不该用乱用。我的做法是构造一批用户请求标注每个请求应该触发哪个 Skill、应该传什么参数然后统计准确率。用户请求期望触发期望参数帮我把这个表格去重clean_skilldeduptrue分析下这份日志的错误分布log_skill无把这张图转成表格不触发 clean_skill无清理下数据clean_skill默认参数跑一遍统计该触发没触发漏报和不该触发却触发误报的比例。漏报和误报的代价不一样漏报让用户觉得 Skill 没用误报可能让 Skill 在不该动的地方乱动。所以对涉及写操作的 Skill我宁可容忍漏报也要把误报压到最低。注意语义层测试的样例要定期更新。模型版本升级、SKILL.md改动、甚至用户表达习惯变化都可能让原本准确的触发变得不准。这是一项持续工作不是一次性任务。3.5 测试里最容易踩的三个坑第一个坑只测 happy path。正常输入跑通就以为万事大吉结果上线后遇到一个空文件直接崩。边界和异常样例必须占测试集的一半以上。第二个坑断言太死。把模型输出的完整字符串写进断言模型换个措辞测试就红。应该断言关键信息比如输出包含 3 行日期格式为 YYYY-MM-DD。第三个坑测试不可复现。模型有随机性同样的输入两次结果不同测试就变成薛定谔的绿。解决办法是把温度参数调低、固定随机种子或者把断言放宽到行为层面。测试的价值在于稳定复现不可复现的测试不如不写。4. 安全上线从权限到回滚的完整清单4.1 上线前必须回答的五个问题Skill 上线前我会逼自己回答五个问题。任何一个答不上来就不上线它最坏能造成什么后果删数据、发请求、改配置最坏情况是什么出错了怎么发现有没有日志、有没有告警出错了怎么回滚能不能一键恢复到上一个版本权限给多了吗它真的需要写权限、网络权限吗谁能停掉它有没有一个开关能立刻禁用这五个问题对应上线的五个维度影响面、可观测性、可回滚性、最小权限、紧急制动。缺一个都是隐患。4.2 最小权限能只读就别给写权限是 Skill 安全的第一道防线。原则很简单能只读就不给写能限定目录就不给全盘能不联网就不联网。具体到配置上我会给 Skill 明确声明它需要的能力而不是默认全开permissions: filesystem: read: [/data/input/**] write: [/data/output/**] network: false shell: false这份配置的意思是只能读input目录、只能写output目录、不联网、不执行任意 shell。范围越窄出事时爆炸半径越小。很多事故不是因为 Skill 逻辑错而是因为它有它根本不需要的权限。4.3 错误处理让 Skill 优雅地失败一个成熟的 Skill不是永不失败而是失败时表现可控。我要求所有 Skill 满足失败时返回结构化错误包含错误类型、原因、建议动作。不吞异常。捕获了就要处理或上报不能静默忽略。写操作前先备份。哪怕只是改一个文件也先留个副本。幂等。同一个操作执行两次结果和执行一次一样避免重试导致重复写入。举个错误返回的例子{ status: error, error_type: INVALID_INPUT, message: 第 3 列包含无法解析的日期格式not-a-date, suggestion: 请检查第 3 列数据或指定 date_format 参数跳过自动推断 }这种结构化错误让 Agent 有机会自我修正——它读到 suggestion 后可能就会去检查数据或调整参数而不是直接崩溃。4.4 灰度与回滚别一次性全量推上线最忌讳一把梭。我的做法是灰度发布先让 Skill 在一小部分场景或一小部分用户上跑观察一段时间没问题再逐步扩大。灰度期间重点看三个指标触发率实际被调用的频率是否符合预期。成功率执行成功的比例。异常率报错、超时、被用户打断的比例。任何一个指标异常立刻回滚。回滚方案要提前准备好不能等出事了才想。最简单的回滚就是保留上一个版本的 Skill 目录出问题直接切回去。版本管理用 Git 就够了每次上线打一个 tag回滚就是 checkout 上一个 tag。提示回滚不只是代码回滚还要考虑数据回滚。如果 Skill 已经写了数据切回旧版本并不能撤销已写入的内容。所以涉及写操作的 Skill上线前一定要想清楚数据层面的回滚策略。4.5 上线后的监控三个必须盯住的信号Skill 上线不是终点而是监控的起点。我盯三个信号第一个是调用量突增或突降。突增可能是误触发突降可能是触发描述失效。两者都值得查。第二个是错误类型分布。如果某一类错误突然增多说明某类输入场景没覆盖好需要补测试样例。第三个是用户中断率。用户频繁打断 Skill 的执行说明它的行为不符合预期可能是步骤太啰嗦也可能是决策太激进。这三个信号不需要复杂的监控系统一份结构化的日志加上定期人工 review 就够了。关键是要有人看没人看的监控等于没有。5. 上线之后Skill 的持续维护与迭代节奏5.1 版本迭代小步快跑每次只改一件事Skill 上线后一定会改。我的迭代原则是每次只改一件事要么改触发描述要么改某个步骤要么改参数。一次改多个地方出问题时根本不知道是哪个改动导致的。每次改动都走一遍改 → 测 → 灰度 → 全量的流程哪怕只是改了一句描述。听起来繁琐但这是唯一能保证质量稳定的方法。我见过太多就改一行应该没事结果翻车的案例。5.2 收集反馈用户怎么用比你怎么想更重要Skill 的真实使用情况往往和设计时的预期不一样。用户可能用它做你完全没想到的事也可能在你以为会用的场景里根本不用。这些信息只能从实际使用中收集。我会定期看两类反馈显性反馈用户主动提的意见和隐性反馈日志里的调用模式。隐性反馈往往更有价值——用户不会专门告诉你我每次都要手动改一下参数但日志里会显示这个模式。5.3 什么时候该退休一个 SkillSkill 也有生命周期。当出现以下情况时该考虑下线它长期低触发几个月没人用说明需求不成立或触发描述有问题。被更好的方案替代有了更通用的 Skill 覆盖了它的功能。维护成本高于价值每次模型升级都要大改投入产出不划算。下线一个 Skill 和上线一样需要谨慎先停止触发改描述或禁用观察一段时间确认没有依赖再彻底移除。直接删除是最危险的做法因为你不知道有没有人还在依赖它。5.4 我个人的几条经验最后分享几条踩坑换来的经验都是文档里不会写的第一Skill 的复杂度要克制。一个 Skill 只做一件事做透。功能越多的 Skill触发描述越难写准测试越难覆盖上线越容易出事。宁可拆成三个小 Skill也不要合成一个大而全的。第二测试样例要当资产维护。每遇到一个线上问题就把它变成一个测试样例。日积月累你的测试集就是最宝贵的回归资产比任何文档都管用。第三上线前找个局外人读一遍SKILL.md。你自己写的东西脑子里会自动补全没说清楚的地方。找个不了解背景的人读他卡壳的地方就是模型会卡壳的地方。第四给每个 Skill 写一份事故预案。一句话说清楚如果它出问题了第一步做什么。这份预案平时用不上出事时能救命。写 Skill 这件事技术难度其实不高难的是那份把它当生产系统对待的敬畏心。能跑通的 Skill 满地都是敢上线的 Skill 才是真正有价值的。把触发描述写准、把测试做扎实、把权限收窄、把回滚备好这四件事做到位你的 Skill 就从玩具变成了工具。