把工作流沉淀成技能：我的 Skill 设计方法论

一、为什么需要「技能」

同一个任务第三次做的时候，就该停下来想一件事：前两次的经验去哪了？ 如果答案是「在聊天记录里」，那这些经验约等于不存在——下次还要重新踩一遍坑。

技能就是把「工作流 + 坑位 + 路由」打包成可复用的资产。我现在有二十多个技能：短剧创作体系、ComfyUI 流水线、RAGFlow API、长视频笔记、录屏拆解、模型部署……这篇讲设计它们时沉淀下来的方法论。

二、SKILL.md 的结构：每一行都有职责

一个技能就是一个带 front matter 的 Markdown，结构高度模板化：

1
2
3
4
5
6
7
8
9
10
11
12
---
name: skill-name
description: 什么时候用我——包含触发语，写用户的原话
---

# 标题
## 0. 铁律（开工前必读，放最前）
## 一、主流程（SOP）
## 二、参数正解表 / 决策表
## 三、脚本速查
## 四、本机硬事实（照抄，别重新踩）
## 五、参考资料（按需读，SKILL.md 保持瘦身）

几个字段的真实职责：

  • description 是路由的唯一入口。用户说一句话，系统靠它决定用不用这个技能。所以触发语要写用户的原话（「把这段文本做成短剧」「查知识库」「总结一下这个视频」），不要写术语；
  • 铁律放最前，因为踩过血泪坑的规矩必须在任何操作前被读到。ComfyUI 那篇的「自己看图自己判卷」就是铁律；
  • references 按需读：SKILL.md 只留骨架和结论，重的模板、排错表进 references/ 子文件——主文件是要被高频加载的，每行都占上下文；
  • scripts 可执行：能脚本化的别描述，selftest.py 只在安装排障时跑。

三、五条设计原则

1. 结论前置，论证后置

每个技能开头放「核心结论速览」表。未来的自己（或别的 Agent）来查，三秒钟拿到答案，细节按需往下读。技能是工具书，不是教科书。

2. 硬事实写死「照抄，别重新踩」

本机环境类结论（代理 10809 吞 localhost、Git Bash PATH 坏、netstat 输出 GBK）全部写进「本机硬事实」段，配文「照抄，别重新踩」。这类坑的共同点是：不踩的时候永远想不起来，踩的时候浪费半小时。

3. 边界写死：工具不伪造它没做过的事

生产类技能保留 preview → confirm → run 三道门；导出类技能明确「快照不声称审批」（asserts_approval 恒 false）；排障类技能写明「按文件存在性复核，不信子代理回复」。边界是技能可信度的来源——一个会吹牛的技能比没有技能更危险。

4. 决策落盘，不信会话记忆

跨会话会忘的事（项目配置、模型选择、已确认参数）一律走决策档案：先写 JSONL 决策记录，再 publish/accept/set-authority 三步写入。会话里的一句点名不落盘，下一轮就退回通用路径——这是用「方言和时长重猜」换来的设计。

5. 从血泪里来，到铁律里去

每个技能的「铁律」和排错表，背后都有具体的事故。写技能时定期问自己：上次在这个流程里浪费时间最长的一次是因为什么？ 那个答案就该是铁律的第一条。没有事故记录的技能，说明用得还不够多，或者复盘得不够深。

四、一个技能的诞生过程

以 ragflow-api 为例，完整走一遍方法论：

  1. 第一次做：手动调 API，踩遍三层响应、101 报错、上传≠解析；
  2. 复盘：把 11 条实测结论按「现象 → 原因 → 处理」整理成表（哪个字段名对、哪个值根本不存在、什么分数算正常）；
  3. 封装：写成 CLI（ping/kb/doc/chunk/retrieve/chat/ask/agent 九组命令），端点逐个对照源码验证，不是抄文档；
  4. 固化：SKILL.md 只留命令表 + 实战结论 + 排错表，重的进 references/api-map.md；
  5. 后续：每次遇到新坑（比如发现 v0.27.2 没有 general 切块），回写技能——技能是活的，越用越厚。

五、收益

  • 对自己：同样的错不犯两次，通勤路上都能凭记忆复现整套流程；
  • 对协作：任何会话接手任务，加载技能就等于加载了我全部经验；
  • 对面试：这套东西本身就是作品——「我把工作流沉淀成了可复用的技能资产」比「我会用某个工具」高一个维度。

六、小结

技能设计的本质是把个人经验变成组织资产。方法论浓缩成五句：结论前置、硬事实写死、边界写死、决策落盘、血泪进铁律。下一篇预告：聊聊 12G 显存以外的战场——工具链自动化。