结论先行:判断一个流程该不该做成 skill,标准是你愿不愿意第三次为它翻聊天记录。第三次出现的手工流程,就是 skill 的立项信号。
从对话到 skill 的路径
一个典型演进:
第 1 次:对话里现场推排查步骤,磕磕绊绊跑通
第 2 次:把上次的步骤粘出来改改,勉强复用
第 3 次:写成 SKILL.md,触发条件、步骤、坑位固化
第 N 次:一句话触发,稳定执行
这个路径的价值在于自带缓冲:第 1、2 次不急着固化,因为你还不知道哪些步骤是本质、哪些是当时环境的偶然。第三次再动手,写出来的已经是被验证过两轮的版本。急着第一次就固化,固化下来的往往是错的或者过拟合的。
立项信号还有几个变体:同事来问第二次同样的流程;自己在另一个项目里凭记忆复述了一遍步骤;或者发现翻聊天记录比写文件还慢。信号的本质是同一件事——这个流程的知识正在以低密度的方式重复存储,每次都付一份对话成本,却没换来复利。
SKILL.md 骨架模板
---
name: test-env-log-query
description: 测试环境服务日志检索
何时用我:需要查测试环境某服务日志、按关键字过滤报错时
不适用:线上近 3 天日志走 fylog;3 天前的历史日志走 ssh-cli
---
## 前置确认
- 服务名、环境标识、时间窗口,缺一项先补齐再动手
## 步骤
1. 用过滤命令拉最近 N 行日志
2. 按关键字/时间窗筛,只贴命中行 + 行号
3. 需要全量时落盘成文件再分段读,不整灌上下文
## 已知坑
- 日志按小时滚动,跨窗口要合并查询
- 某服务默认 INFO 级别,先调 DEBUG 再复现
头部几行里,“何时用我"决定召回是否正确,“不适用"决定误召回是否被拦截。这两个字段是整个文件的入口——写不准,正文写得再好也轮不到被读。
模板不必每段都齐。小 skill 头部加步骤就够;坑位段是最值钱的部分——步骤写错了会当场暴露,坑不写下来就每次掉进去一次。前置确认段的判断标准:如果缺了某个输入后面必然返工,它就该出现在前置确认里,一个字都别省。
触发条件的三个常见毛病
第一个毛病:把 description 写成功能清单,而不是触发场景。“本 skill 支持日志检索与过滤"是功能说明,但召回匹配的是"用户此刻想干什么”。同一个 skill 换成"需要查测试环境某服务日志、按关键字过滤报错时”,召回立刻变准。差别在主语:功能清单以 skill 为主语,触发场景以问题为主语,而召回发生在问题这一侧。
第二个毛病:只写召回不写拦截。头部的"不适用"行最容易被省略。我库里出过一次典型误召回:一个查线上日志的问题命中了测试环境日志 skill,agent 按测试环境的命令跑了一通,全部失败后才开始换路线,白白烧掉一整段上下文。修复只花了一行字——头部补上"不适用:线上近 3 天日志走 fylog,更早走 ssh-cli”。两个相邻 skill 的边界不是各自独立写出来的,是互相标注出来的:新 skill 入库时,我会顺手去它相邻 skill 的"不适用"行里补上它的名字,这条反向标注比正向召回更容易漏。
第三个毛病:触发条件里埋只有自己懂的缩写。“查 fykc 日志用我"这类写法,对冷启动 agent 是黑话,它会在该不该触发之间犹豫。服务名、平台名要么写全称,要么在正文第一步给对照表。判断标准与冷启动测试同源:陌生 agent 只读头部,能不能不追问任何上下文就决定"该不该用我”——决定不了,这行 description 就还没写完。
哪些流程值得做:判断表
我的库里的高分值流程:环境排障(日志在哪、DB 怎么连、常见报错对照)、造数操作(多步组合、顺序敏感)、代码评审 checklist(机械但条目多)、周报/文档生成(格式固定内容多变)。共同点:步骤多于判断、格式稳定、重复频率高。
| 特征 | 适合做成 skill | 不适合 |
|---|---|---|
| 步骤与判断比 | 步骤多、判断少 | 判断密度高 |
| 格式稳定性 | 输入输出格式固定 | 每次形态都不同 |
| 重复频率 | 一月数次以上 | 一年一两次 |
| 出错代价 | 错了可重来,有对照 | 错了代价高,需现场权衡 |
| 典型例子 | 排障、造数、评审 checklist | 新架构设计、方案技评 |
反过来,纯创作类任务(写新架构设计)不适合做成 skill——判断密度太高,每次都不同,固化反而束缚。
介于两者之间的半结构化流程——大方向固定、局部要临场判断——做成 skill 骨架加判断位的混合体:固定步骤写死,判断点显式标注"此处根据 X 选择 Y 或 Z"。固化的是骨架的确定性,保留的是局部的弹性,比全写死或全不写都好。
与 AGENTS.md 的分工边界
第一年我把所有约定都堆进 AGENTS.md:排查工具怎么选、文档怎么读、造数怎么造,文件很快膨胀到我自己都不想打开。后来划出的边界:AGENTS.md 管规则和路由,skill 管流程细节。判据是加载时机——AGENTS.md 每轮对话都进上下文,只放每一轮都用得上的东西;SKILL.md 只在被触发时加载,装得下整个流程的全部细节。
具体实例:日志查询这件事,AGENTS.md 里只留一行路由——“测试环境日志走 test-env-log-query skill,近 3 天线上走 fylog,更早走 ssh-cli”;命令、参数、滚动规则、权限获取方式全部在 skill 正文。反例我也犯过:曾把造数操作的全部步骤塞进 AGENTS.md,每轮对话都背着一段一月用不了几次的流程文本,直到检查上下文体量才把它移进 skill。瘦身之后 AGENTS.md 的路由反而更清晰——剩下的每一条都是真·每轮需要的东西,长流程在触发时才被完整加载。入库流程因此多了个固定收尾动作:skill 定稿后,检查它对应的路由行在不在 AGENTS.md 里。路由行缺失的 skill 等于修了一条没有指示牌的路,模型不知道它存在,写得再好也白写。
沉淀时最难的是克制:决策树,不是流水账
skill 不是操作日志,是决策树。每一步写清楚"什么条件下做什么",而不是流水账:
流水账(反例):我先连了跳板机,翻了 /data/logs 发现没权限,
又申请权限,等了会儿,然后终于看到日志里有个超时……
决策树(正例):无权限 → 先走权限申请命令,等审批,回到第 1 步
有权限且日志为空 → 检查时间窗口,日志按小时滚动
日志有 ERROR → 按关键字过滤,贴命中行 + 行号
检验方法:让一个没有这段对话史的 agent 冷启动跑一遍你的 skill。流水账能过你这关——因为你的记忆替文件补全了所有省略——但过不了冷启动那关。
步骤的粒度以"一个 agent 一次动作能执行"为限。写"配置好环境"就太粗——agent 要猜哪一步算配置好;写"执行 X 命令,期望输出含 Y"就够执行。粒度粗的 skill 每次执行都在重新发明细节,固化了个寂寞。
维护纪律
skill 会腐烂:系统改了、平台升级了、原来有效的命令失效了。我定了两条:每个 skill 的开头写"何时用我",过时的直接删不归档;版本升级后全库跑一遍冒烟。库的规模不重要,每一条都能一把跑通才重要。
冒烟的做法很朴素:每个 skill 用一句话触发,让它走完最短的一次真实路径——真连一次环境、真查一次日志。跑不通的当场修或当场删,不让带病条目留在索引里。全库冒烟一次成本不高,换来的确定值是"任何一句话派出去都能跑"。
“过时的直接删"值得单独说明:归档旧 skill 的心理账户会诱惑你留一堆"以后可能有用"的文件,它们的存在让索引变脏、召回变差。删掉的内容在版本历史里,真需要时翻得回来。删除前还有个低成本动作:把过时原因写成一行留在记录里。半年后同类需求再出现时,你会想知道当时删的是"平台没了"还是"写得不好”——前者不必复活,后者要重写而不是恢复。
库的分代数据是这套纪律的注脚。库迭代到现在三代,第一代十几个,活下来的不到一半。死掉的三个典型,各代表一类错配:一个 Git 分支操作流程 skill——步骤太少、没有环境私有知识,相对模型自身能力的增量近似为零,写它纯属仪式感,这类错误的本质是把模型本来就会的东西误当成知识资产;一个数据库表结构速查 skill——表结构月月变,skill 永远比线上慢一拍,维护成本超过收益,这类知识正确的归宿是自动生成的文档或直接查库,放进一个不会自动更新的文件里注定腐烂;一个错误码对照表 skill——它本质是数据不是流程,纯查阅类内容做成 skill 是品类错配,步骤间的顺序与分支才是 skill 的领土。活下来的共性则是另外三条:有环境私有知识(日志在哪、权限怎么拿,训练语料里不可能有)、顺序敏感(顺序错必返工,模型自由发挥时选不对)、坑位密度高(不写就每次掉)。现在新增 skill 前先拿这三条过筛,过不了的写成普通文档。活过三代的那些 skill 几乎没人再改过——稳定的 skill 有共同的样子:步骤不长、外部入口稳定、坑位早已写尽。
真实场景
测试环境日志查询是我沉淀的第一个 skill。头两次在对话里现场推步骤:日志在哪、怎么过滤、权限怎么拿,每次十几轮起步。第三次动手前又要翻聊天记录时,我意识到这就是立项信号,当天写成了 SKILL.md。第一版犯的就是流水账错误——按我自己的排查经过写,让另一个 agent 冷启动跑,卡在第二步:我不知道自己当年默认了"先切到某个环境标识"这个前置动作,压根没写。重写成决策树、补上前置确认段之后才稳定可用。当时的权衡是:冷启动测试要多花一轮时间,第一版我为了当天收工跳过了它,结果返工的时间远多于省下的那一轮。事后总结两条:一是 skill 的读者不是我自己,是任何没有这段对话史的 agent,写作假设必须换成"它什么都不记得";二是新 skill 定稿前就该做冷启动测试,而我自己是最差的测试者——我的记忆会替文件打补丁。后来我把"冷启动测试"写进模板底部当注释:新 skill 必须由另一个 agent 空跑一次才能定稿。这条小规矩之后,我再没出现过第二次步骤断裂——断裂都在别人空跑时暴露,暴露在我这里就只是改几行文字。
检查清单
- 同一流程第三次手工执行时才立项,不提前固化
- 头部写"何时用我"和"不适用",召回与拦截都靠它
- 正文是决策树:条件 → 动作,不是时间线流水账
- 有前置确认段,默认值显式写出来
- 定稿前让另一个 agent 冷启动跑通一遍
- 过时 skill 直接删,不归档,索引保持干净
- description 写触发场景不写功能清单,相邻 skill 互相标注"不适用"
- AGENTS.md 只留一行路由,流程细节全部收进 skill 正文