技能工程 — 从需求到上线的全流程
这一章讲五件事: 需求怎么在 5 分钟内定下来;设计阶段的四个技巧; 实现阶段人和智能体怎么分工;测试怎么从「感觉还行」升级成评测循环; 以及上线时自用、团队、社区三档各要做什么。 读完你能把一个自用技能,养成一个敢发给别人用的技能。
1. 在我机器上能跑 ≠ 谁用都靠谱
先看事故现场。 作者把技能打包发给三个朋友,全部翻车1:
- 朋友 A:翻译技能英翻中不错,换其他语言不好用——作者日常只用英翻中,从没考虑过别的语种;
- 朋友 B:文章配图技能不能画图——作者自己配了 Gemini 的 API Key,朋友没有;
- 朋友 C:上传 PDF 直接卡死工作流——作者只传过 Markdown,从没做容错设计。
三个人、三个坑,同一个根源:做这个技能的时候,压根没想过别人会怎么用2。 给自己用,你知道该说什么、给什么格式、绕开哪些坑;给别人用,这些隐含假设大部分不成立3。
软件工程早就为这个问题准备了一套方法——五个阶段:需求分析 → 设计 → 实现 → 测试 → 上线与发布, 书套到技能开发上,发现完全适用4。前五章你其实一直在做前四件事,只是凭直觉; 本章把直觉变成习惯,并补上最后一环。
2. 需求:5 分钟填一张需求卡
好技能从真实痛点长出来:反复手动做一件事 → 发现每次都在重复相同步骤 → 尝试用提示词固定 → 发现提示词的局限 → 封装成技能。每一级跃升都由实际痛点驱动,不是坐着想出来的5。
真要动手了,写不出来多半是还没想清楚。别急着开文件,花 5 分钟填一张技能需求卡,回答 6 个问题6:
| 问题 | 以书里的「小红书信息图技能」为例 |
|---|---|
| 解决什么问题 | 把文章自动拆分为小红书风格的系列信息图 |
| 触发场景 | 用户说「帮我做一组小红书图片」 |
| 输入 | 一篇文章(Markdown 文件或直接粘贴) |
| 输出 | 每张图的大纲文件 + 生成的图片文件 |
| 规则 | 竖版 3:4,卡通手绘风,每张只传达一个核心信息 |
| 禁止清单 | 不能用写实风格;不能跳过大纲确认直接生成 |
这 6 个答案,基本就是 SKILL.md 的骨架。书同时给了一颗定心丸:需求不需要完美—— 先写初版,在实际使用中迭代;小红书技能的第一版只有一种视觉风格,两周后才长出多种风格组合7。
3. 设计四招:踩坑点、可容错、可扩展、跨对话记忆
技能的第一版总是挺好的,问题都出在后面:用一阵子开始出毛病,改一处别处坏,加新功能要大改。 设计阶段的四招,分别管过去的教训、当下的意外、未来的变化和长期的积累8。
第一招:踩坑点(gotchas)——记下反复犯的错。 书引了 Anthropic 内部几百个技能的经验:一个技能里信息密度最高的部分,往往不是流程说明,而是踩坑点—— 智能体用这个技能时反复犯的错9。这些错事前根本预见不了,都是用出来的;像做熟了番茄炒蛋之后, 在菜谱空白处用铅笔写下「先下蛋再下番茄」「油温别太高」。所以每个 SKILL.md 都该预留一个 「踩坑点」部分,第一版是空的都行,发现一个加一个。书里给的真实例子非常传神:
「总以为把模板放到 references/ 目录下,智能体自己就会去找,结果发现它根本不会主动跨文件读取。 每次生成前必须加一句强提醒:先读取 report-template.html,再生成 HTML 报告」10
踩坑点和禁止清单的区别在时间线:禁止清单是事前设计就能想到的硬性底线(管「不许做什么」); 踩坑点是事后使用中才暴露的意外盲区(管「容易在哪里栽跟头」)。两者并行不悖11。
第二招:可容错——假定一定会出现意外。 软件开发的铁律:永远不要假设用户会按你期望的方式 使用你的产品(朋友 C 的 PDF 就是这么来的)12。三个着手点13:
- 开头检查输入:文件是不是空的?格式对不对?内容是不是太长?发现不对就提醒用户别继续—— 写作流程技能第一步就检查文件类型,遇到 PDF 提醒「当前仅支持 Markdown,请转换 后重试」,流程就不会卡死;
- 关键步骤人工确认:小红书技能最初没有确认环节,智能体分析完直接生成所有图——方向不对,图全白费;
- 中间结果随手存文件:图片生成失败了,写好的提示词文件还在磁盘上,重跑不用从头来; 翻译中断了,已译段落都在,从断点继续。
第三招:可扩展——随时加新功能不改主文件。 软件工程的「开闭原则」(对扩展开放、对修改关闭) 套到技能上:把「稳定的流程」和「变化的细节」分开14。书给了两个真实手段:
- 用维度组合替代穷举。封面图技能最初穷举风格(极简风、赛博朋克风……),总也列不完,每加一种改一次主文件。 后来拆成六个维度——构图类型、色彩方案、渲染风格、元素密度、情绪调性、文字布局—— 总共只维护 32 个选项,排列组合却能产生 18900 种变体;新增一个选项自动适配所有维度15;
- 扩展文件(EXTEND.md)。团队共享技能时,个人/项目的自定义写在
.baoyu-skills/<技能名>/EXTEND.md(项目级)或~/.baoyu-skills/…(用户级), 智能体执行时先读扩展文件覆盖默认值——不改原技能,互不干扰。 注意扩展文件别放在技能安装目录,升级会被覆盖16。
还配了一 条刹车:YAGNI(You Aren't Gonna Need It,你不会需要它)——扩展性是跑通之后才需要考虑的。 过早为「将来可能的需求」做设计,只会增加不必要的复杂度17。
第四招:跨对话记忆——记住上次做到哪。 有些技能的效果取决于「记不记得上次做了什么」。 作者的微信群聊精华技能,第一版每次都从头汇总,昨天的内容今天又出现一遍;解法是按群建目录、 精华按日期存文件,再维护一个 history.json 记录上次汇总到的最后一条消息的时间—— 下次运行先读时间,只拉新消息18。第 08 章的数据分析技能也用这个模式:记录上次分析的数据文件和核心发现, 新数据来了主动对比变化19。记录文件同样要放稳定目录,防止技能升级时被删。
设计完,过一遍八项检查清单:单一职责、按需加载、可预测(有输出格式和示例)、可容错、可扩展、 跨对话记忆、踩坑点、禁止清单20。
4. 实现:你决策,它执行
技能本 身就是给智能体用的——「它比我们更清楚什么样的指令更适合自己,让使用者自己来写使用说明, 自然比外人写得更到位」。所以实现阶段的人机分工是:你定需求和标准(决策者+验收者), 智能体负责写和改(执行者)21。
节奏上不求一步到位,技能按文件夹结构的演进自然长出四个阶段22:
- 跑通 MVP(最小可行产品,只做核心功能够用就上):核心指标只有一个——能用; 第一版越简单越好;
- 功能补齐:做加法。真实使用中不断发现缺失,高频修改 SKILL.md 打补丁;
- 架构重构:做拆分。补丁多了必然臃肿,把背景知识抽到 references/,或拆成两个技能;
- 持续优化(长期):打磨边界情况、歧义表述、词元消耗,从「能跑」到「靠谱」。
书给的量级参考:小红书信息图技能从手动提示词模板,到约 200 行的初版 SKILL.md, 经过 20 多次迭代,长成 641 行的主文件 + 26 个参考文档的多文件结构23。
5. 测试:评测循环
先看反面。 作者第一次给翻译技能评分: 先跑一遍,觉得「挺好的」,再定标准—— 后来才意识到判断力被第一印象「绑架」了:「就像考试先看了答案再出题,题目就会不自觉地往答案上凑」24。 解法是把顺序反过来:先定考题(测试用例),再测考生。
这套方法在 AI 工程界叫评测(Evaluation,简称 Eval),Anthropic 和 OpenAI 都在官方文档中推荐用它迭代技能; 本质就是一个循环:备考题 → 定标准 → 跑一遍打分 → 哪里不好改哪里(再跑)25。 循环最大的意义不只是证明当前版本好,更是防退化:你为场景 A 加的新规则, 很可能悄悄把原本好好的场景 B 搞崩26。
测试用例怎么写? 一个用例 = 指令 + 输入 + 期望结果。刚起步两三个就够,但有三条要求27:
- 指令要像真人说话(「帮我整理一下」「这个太长了,提炼重点」, 而不是「请使用会议纪要技能处理以下转录稿」);
- 覆盖多种情况:一个正式一个口语,一个短一个长,最好带个边界(大段闲聊、格式不规范);
- 别忘了反例,而且反例要拿真正容易混淆的——「帮我把这段话改得更通顺」 (和翻译沾边,其实需要润色),而不是「写个斐波那契函数」这种一眼假的。 反例比正例(应该触发的样例)难写,也更有价值。
失败案例要做两个动作:踩坑点写进 SKILL.md(教智能体做事),测试用例存进独立题库(留案发现场)—— 千万别把考题写进 SKILL.md,那会干扰智能体正常运行28。
评分标准 = 客观检查项:要具体到能直接判对错——「纪要包含待办事项清单」「每个待办标注负责人」 「篇幅不超过原文的 30%」,以及别忘了「技能被正确触发」本身就是一个检查项; 不合格的写法是「输出质量好」(没法判)和「必须出现『总收入:X$』精确措辞」(换个说法就失败,太脆弱)29。 检查项可以后补:先跑一遍,看到「不够好」的结果,才说得清「好」长什么样30。
主走查:给会议纪要技能打一次分
关键操作:同一个测试用例跑两遍——一遍用技能,一遍不用。为什么? 评测的价值不在于看绝对输出有多好,而在于相比「裸跑」把下限提升了多少: 不用技能能拿 80 分 、用了 85 分,这技能可能不值得维护;30 分到 90 分,价值一目了然31。
跑完严格执行三个动作32:
- 整理评测记分表,打分两条原则:看实质不放水(输出里确实有「待办事项清单」这一节, 但只有一句模糊的话——不通过,有标题不等于有内容);判对错同时记依据;
- 主观验收,写下「工程化」的反馈——检查项管客观(有没有、对不对),人眼管主观(好不好、顺不顺), 两条腿走路。反馈必须具体可执行:「第三段把 context window 翻译成了『上下文窗户』,应统一为 『上下文窗口』」,而不是「翻译得很死板」——大模型听不懂情绪,只听得懂指令;
- 算一笔质量与耗时的经济账:技能把质量从 40 分提到 85 分,但耗时从 5 秒变 30 秒—— 这就需要取舍了。
其中记分表长这样(书里会议纪要技能的示例口径)33:
| 检查项 | 有技能 | 无技能 | 依据(记下来) |
|---|---|---|---|
| 纪要包含待办事项清单 | 通过 | 不通过 | 无技能版漏了待办 |
| 篇幅不超过原文 30% | 不通过 | 不通过 | 原文 3000 字,纪要 1800 字,占比 60% |
| 技能被正确触发 | 通过 | — | — |
对症下药有一条铁律:治病治根。 只为眼前某个用例打补丁,「本质上跟考试前背答案没区别, 换道题就不灵」。书用回了第 01 章那个例子:翻译技能把 LLM 翻成「法学硕士」—— 打补丁是加一条「LLM 应翻译为大语言模型」,只救一个词;通用解是 「根据文章所属领域判断术语含义,优先采用该领域的通用译法;如无通用译法,保留英文原文」—— 连 agent 该译「智能体」还是「代理人」、hallucination 该译「幻觉」还是「幻想」也一并覆盖了34。
什么时候停?反馈都是空的,或者连续两轮改进幅度很小。三条实操心法: 检查项本身也要迭代(太容易过=没区分度,太难过=要么不合理要么技能要大改); 老技能升级的对比基线(用来比较的参照版本)不是「没技能」而是改之前的老版本(先备份再改); 把没通过的检查项和主观问题一起发给智能体让它提修改方案——但改不改、怎么改,你拍板35。
6. 上线与发布:三档要求
发布动作取决于给谁用,三档要求逐级叠加36:
个人自用:过 一遍安全清单(权限控制:读哪些目录、写不写出界、要不要联网;
不可逆操作保护:删除前二次确认、覆盖前先备份)37。
进阶玩法:Claude Code 的钩子(hook)机制可以搭「按需防护」——比如用 /careful 指令进入严格模式,
PreToolUse 钩子在执行命令前检查,碰到 rm -rf 这类高风险操作直接拦截。注意这不是内置的安全开关,
而是钩子(底层机制)与技能(触发方式)的组合38。
团队分享:两件事必须提前想好。怎么分发——放项目代码仓库(如 .claude/skills)成员自动获取,
或搭内部技能市场(避免把所有技能塞进每个人的上下文);怎么保证质量——Anthropic 内部的做法是
先在沙盒里试用或在 Slack 推荐给同事,获得足够关注再正式发布;一般不需要审核委员会,
但需要「发布前有人用过、觉得好用」的机制39。
社区发布:用户决定装不装一个技能,整个过程可能不超过一分钟,只关心三件事:
简介能不能看懂、有没有示例判断效果、装完能不能跑通40。发布前自查:重新审视 description
(面向陌生人覆盖常见触发说法);写说明文档(功能+示例+依赖+兼容性);
清理个人信息(搜 key、token、password、绝对路径;密钥用 <YOUR_API_KEY> 占位符代替——
含私密密钥的技能不要上架);加版本号41。各平台细节不同,但本质上都要提供三样:
唯一标识(slug)、语义化版本号、说明文档。
发布之后才是真正的开始:留意反馈持续迭代,注意向后兼容——改了触发词或输出格式, 正在用的人会受影响;优先用外挂扩展加新功能,不强行改变老用户的习惯。停止维护的技能, 在 README 里标注并推荐替代方案,比放着不管好42。
7. 作者的判断与证据,边界与局限
书里的判断(有事故证据): 「需求没想清楚,后面写得再好也可能是在错误的方向上努力」—— 证据就是开头三个朋友的翻车,三个坑分别对应语种、环境、输入格式三类隐含假设43。
书里的判断(引用一手实践): 「信息密度最高的部分是踩坑点」引自 Anthropic Claude Code 团队工程师 的文章;评测循环标注了 Anthropic 与 OpenAI 官方文档——两处都是一手来源,书里给了出处44。
书里的判断(经验法则,未给数据): 「反例比正例难写,也更有价值」「获得足够关注再正式发布」—— 属作者与所引团队的实践经验,不是实验结论。
边界与局限:
- 评测循环是手工流程;书末尾提了一句编码智能体能自动跑测试生成对比报告,但没展开做法;
- 「18900 种变体」的扩展设计适合「个性化定制」类技能,书自己也限定了适用范围;
- 社区发布的平台流程(扣子、ClawHub、GitHub)随版本变化快,书明确说以各平台文档为准。
8. 可带走的
主走查一行复述: 同一个会议纪要用例跑两遍——无技能版漏待办、篇幅 1800/3000 字(60%,超 30% 红线) 双不过;有技能版触发正确、待办齐全;没通过的那项成了下一轮 SKILL.md 的修改方向。
- 自用技能 ≠ 可分享技能:发出去之前,把「你默认的所有前提」列一遍;
- 需求卡 6 问(问题/场景/输入/输出/规则/禁止清单)= SKILL.md 的骨架;
- 踩坑点是技能里信息密度最高的部分——预留一节,发现一个加一个;
- 容错三板斧:开头检查输入、关键步骤人工确认、中间结果随手存文件;
- 扩展靠组合不靠穷举(32 个选项 18900 种变体);个人定制写 EXTEND.md,别改主文件;
- 需要跨对话记忆的技能,维护一个 history 文件;记得放稳定目录;
- 先定考题再测考生;测试用例存题库,踩坑点 才进 SKILL.md;
- 评测看下限提升:有/无技能对比打分;「技能被正确触发」也是检查项;
- 修 bug 治根不治标:「按领域判断术语」一招覆盖 LLM/agent/hallucination 三个词;
- 发布三档:自用过安全清单,团队「发布前有人用过」,社区一分钟内讲清「干什么、什么效果、能跑通」。
9. 原文地图
| 主题 | 原书章 | 原文位置 |
|---|---|---|
| 三个朋友翻车 | 第 6 章 | text/07-ch06.txt:11(搜「朋友 A」) · text/07-ch06.txt:13(搜「Gemini」) · text/07-ch06.txt:14(搜「PDF」) |
| 五阶段 | 第 6 章 | text/07-ch06.txt:27(搜「需求分析」) |
| 痛点驱动的诞生过程 | 第 6 章 | text/07-ch06.txt:47(搜「反复手动」) |
| 需求卡 6 问与小红书例 | 第 6 章 | text/07-ch06.txt:69(搜「小红书」) · text/07-ch06.txt:79(搜「3∶4」) |
| 需求不需要完美 | 第 6 章 | text/07-ch06.txt:86(搜「完美」) |
| 踩坑点 | 第 6 章 | text/07-ch06.txt:114(搜「gotchas」) · text/07-ch06.txt:132(搜「跨文件读取」) · text/07-ch06.txt:137(搜「时间线」) |
| 可容错三方面 | 第 6 章 | text/07-ch06.txt:144(搜「期望的方式」) · text/07-ch06.txt:159(搜「检查输入」) · text/07-ch06.txt:106(搜「人工确认」) · text/07-ch06.txt:172(搜「存文件」) |
| 维度组合替代穷举 | 第 6 章 | text/07-ch06.txt:191(搜「六个独立的维度」) · text/07-ch06.txt:196(搜「18900」) |
| EXTEND.md | 第 6 章 | text/07-ch06.txt:200(搜「EXTEND.md」) · text/07-ch06.txt:227(搜「安装目录」) |
| YAGNI | 第 6 章 | text/07-ch06.txt:233(搜「YAGNI」) |
| 跨对话记忆 | 第 6 章 | text/07-ch06.txt:248(搜「history.json」) · text/07-ch06.txt:249(搜「只拉取这个时间之后的新消息」) |
| 设计检查清单 | 第 6 章 | text/07-ch06.txt:276(搜「单一职责」) |
| 人机协作实现 | 第 6 章 | text/07-ch06.txt:302(搜「使用说明」) |
| 四阶段与小红书演进 | 第 6 章 | text/07-ch06.txt:327(搜「MVP」) · text/07-ch06.txt:321(搜「641 行」) |
| 评测循环 | 第 6 章 | text/07-ch06.txt:365(搜「评测」) · text/07-ch06.txt:380(搜「防退化」) |
| 先定考题 | 第 6 章 | text/07-ch06.txt:386(搜「绑架」) · text/07-ch06.txt:390(搜「测试用例」) |
| 用例三要求、反例 | 第 6 章 | text/07-ch06.txt:412(搜「真人说话」) · text/07-ch06.txt:419(搜「斐波那契」) |
| 踩坑点进 SKILL、用例进题库 | 第 6 章 | text/07-ch06.txt:434(搜「案发现场」) |
| 检查项好坏 | 第 6 章 | text/07-ch06.txt:445(搜「待办事项清单」) · text/07-ch06.txt:456(搜「输出质量好」) |
| 对比 打分看下限 | 第 6 章 | text/07-ch06.txt:467(搜「下限」) |
| 三动作 | 第 6 章 | text/07-ch06.txt:480(搜「不放水」) · text/07-ch06.txt:192(搜「情绪」) · text/07-ch06.txt:506(搜「经济账」) |
| 治根:LLM 案例通用解 | 第 6 章 | text/07-ch06.txt:524(搜「法学硕士」) · text/07-ch06.txt:527(搜「通用译法」) |
| 停止条件与三心法 | 第 6 章 | text/07-ch06.txt:532(搜「两轮」) · text/07-ch06.txt:543(搜「老版本」) |
| 三场景与安全清单 | 第 6 章 | text/07-ch06.txt:573(搜「逐级叠加」) · text/07-ch06.txt:582(搜「权限控制」) |
| 钩子 | 第 6 章 | text/07-ch06.txt:602(搜「钩子」) · text/07-ch06.txt:609(搜「rm -rf」) |
| 团队分享 | 第 6 章 | text/07-ch06.txt:620(搜「技能市场」) · text/07-ch06.txt:627(搜「有人用过」) |
| 社区发布 | 第 6 章 | text/07-ch06.txt:632(搜「不超过一分钟」) · text/07-ch06.txt:649(搜「占位符」) |
| 发布之后向后兼容 | 第 6 章 | text/07-ch06.txt:695(搜「向后兼容」) |