Skills 与渐进式披露
上个月同事把一个「月度对账」的活交给了 Agent:读三张 Excel,统一表头,清洗金额,按客户编码合并,输出差异表。第一次跑,结果不错。第二周换了一份新月份的文件,它把「1,234.50」当成了字符串,求和变成了拼接,差异表凭空多出两百多行。第三周更离谱,它把一张只有 12 行的表当成重复数据删掉了,而那是汇率调整表,删了之后所有外币客户的金额全部对不上。
三次失败,三个不同的原因,但根子是同一个:它每次都在临时想。没人告诉过它金额列带千分位,没人告诉过它这张 12 行的表不能动。这些知识不在模型权重里,也不在当时的 prompt 里,只存在同事的脑子里。
后来我们把这些东西写成了一份 Skill:一张带检查点的操作卡,加两个已经调好的脚本。同样的活,成功率从「三次里成一次」变成了「连着两个月没出问题」,平均轮数也从 23 轮降到 9 轮。
这就是我理解的 Skill:它不是知识库,而是把已经验证过的动作序列固化下来,让模型照着做,而不是每次重新发明一遍。
一、Skill 沉淀的不是知识,是动作
RAG 和 Skill 经常被混为一谈,其实它们解决的是两个不同的问题。RAG 回答「这件事的事实是什么」,Skill 回答「这件事该按什么顺序动手」。
我更愿意用老饭馆的配方卡来类比。一家开了二十年的面馆,汤的咸淡不靠新厨师的悟性,靠灶台边上那张塑封卡片:几号锅、多少水、几克盐、大火几分钟、转小火几分钟、出锅前尝一口。卡片本身不值钱,值钱的是它把老师傅的手感翻译成了可重复的动作,并且每一步都留了一个当场能判断对错的检查点。新厨师第一天上岗就能做出八成水准,剩下两成靠练,但不至于把一锅汤做废。
一份能用的 Skill 里通常有三样东西,外加一样可选的:
- 触发条件:什么情况下该翻这张卡。写不清这一条,卡片就永远躺在抽屉里。
- 动作序列:先做什么、后做什么、哪一步依赖哪一步的产出。
- 检查点:每一步怎么确认自己没做错。缺了这一样,模型会带着错误一路往下跑。
- 调好的工具:能机械执行的部分,做成脚本放进
scripts/,别让模型现场写。
把这四样对齐之后,再看「为什么不能让模型临时想」,原因就具体了。
模型的输出是概率采样,同一个任务跑两次,路径很可能不同:第一次先检查表头,第二次先做类型转换,第三次干脆跳过了空值统计。它也没有「上周踩过这个坑」的记忆,上下文一压缩,前面确认过的约束就消失了。它对业务约定更是一无所知,只能从数据形态里猜:看到一列数字,它不知道这列是金额还是数量,也就不知道千分位该不该去掉。
Skill 做的事情,是把这些不确定性从「每次生成」搬到「写一次、审一次、之后复用」。代价同样明确:流程被锁死了,遇到 Skill 没覆盖的分支,模型可能硬套步骤;业务变了而 Skill 没更新,它比没有 Skill 更糟,因为它会非常自信地执行一套过期流程。
所以判断一个任务该不该做成 Skill,我只看三个条件:流程是否稳定、是否重复发生、出错代价是否够高。三个都满足才动手。一次性的探索任务写成 Skill 是浪费,流程每周都在变的任务写成 Skill 是负债。
二、一个 Skill 的目录长什么样
Skill 的物理形态就是一个目录。Agent 启动时扫描技能目录,读出每个 SKILL.md 的头部信息,建立索引;判断相关了再读正文;正文里提到参考文档或脚本,才继续往下取。目录结构大致是这样:
1 | skills/excel-data-cleaning/ |
每个位置的分工,比目录长什么样更重要:
| 位置 | 放什么 | 什么时候进上下文 | 典型体量 |
|---|---|---|---|
SKILL.md 头部 |
name、description | 会话开始就常驻索引 | 30~60 token |
SKILL.md 正文 |
判定条件、步骤、检查点、失败处理 | 命中后才加载 | 600~1500 token |
reference/ |
字段口径、错误码、边界案例 | 正文指向时才读 | 2k~10k token |
scripts/ |
可直接执行的脚本 | 永不进上下文,只读用法 | 0 token |
这张表背后只有一条判断标准:这段内容,模型需要「理解」还是只需要「执行」?
需要理解的东西留在正文里,比如「什么时候必须停下来问人」「两种去重规则的差别」。只需要执行的东西一律脚本化,比如读 sheet 名、去掉千分位、校验行数守恒。让模型读一遍两百行的 pandas 代码再去执行,既贵又容易读错;让它跑一条命令、看一行 JSON 输出,又快又准。
还有一个容易忽略的细节:目录名和 name 字段要保持一致,且用稳定的英文短横线命名。原因很实际——Agent 的路由、日志、评测报告里都会出现这个名字,改一次名字等于让所有历史记录对不上号。名字是接口,不是标题。
另一个决定成败的是切分粒度。我见过一份「数据处理」Skill,里面同时管 Excel 清洗、CSV 合并、图表生成,正文六百多行。它的失败方式很典型:模型读到第七十行就丢了主线,最后只执行了第一个分支。后来拆成三份,每份不超过一百二十行,触发准确率和成功率同时上去了。粒度原则只有一条:一份 Skill 对应一类可命名的任务。如果你没法用一句话说清它管什么,那就是该拆了。
至于 Skill 放在哪儿,各家 Agent 的实现不同,有的读项目目录下的约定路径,有的读用户级目录,有的两边都读并按优先级合并。这件事要在团队里定死并写进 README,否则同一个任务在不同人机器上加载的技能集不一样,排查问题时连基线都对不齐。
三、一份完整的 SKILL.md
下面这份是「Excel 数据清洗」的实例,改过敏感信息,但结构和我们线上用的是同一套。
1 | --- |
这份文档有几个刻意的设计。
每个步骤后面都跟一条「校验」,而且校验的形式是可观察的输出,不是「确认无误」这种空话。模型能读到实际的数字,才知道自己有没有做错。
失败处理按「退出码」组织,而不是按自然语言描述。原因是脚本的退出码是确定性的,模型只需要查表;如果写成「如果出错了就看看情况」,模型每次的反应都会不一样。
边界一节全部用否定句。这不是文风偏好,是经验:模型的默认倾向是把任务做完,正面要求它可能打折扣执行,否定句是少数能真正拦住它的东西。「不覆盖原文件」这五个字,比前面所有步骤加起来更能防事故。
四、触发机制:description 是路由,不是简介
索引里每条 Skill 只留下一行名字和一段 description。模型做的事情,本质上是把当前对话和这几十条描述逐一比对,挑出最相关的。所以 description 的写法直接决定命中率,它是路由规则,不是产品介绍。
最常见的错误写法是描述「我是什么」:
1 | description: Excel 数据处理工具,支持读取、清洗、转换和导出。 |
这段话信息量为零。模型读完不知道什么时候该用它,也不知道它和其他两个表格类 Skill 的区别。「数据处理」这四个字能匹配上的场景太多了,结果是哪个都命中、哪个都不准。
同一件事,换成写「什么时候用我」:
1 | description: 清洗业务方提供的 Excel 报表(.xlsx/.xls),统一表头、修正金额与日期类型、按业务主键去重,并输出清洗报告。当用户要求整理、合并、核对表格数据,或提供的文件存在合并单元格、千分位金额、多格式日期时使用。不用于从零生成新报表,也不用于数据可视化。 |
差别在三处。
用用户的词,不用内部的词。 用户会说「这表太乱了帮我理一下」「两个表对不上」,不会说「执行 ETL 预处理」。description 里要出现这些口语说法,模型才有机会把日常表达映射过来。
写输入特征。 「合并单元格」「千分位金额」「多格式日期」这些是脏数据的形态,也是判断任务类型最可靠的信号。只写任务名不写输入特征,遇到换个说法的请求就漏了。
写排除项。 「不用于从零生成新报表」这句的作用,比前面所有包含项都大。因为误触发比漏触发更伤:漏触发最多是模型自由发挥一次,误触发会把一套不相干的流程灌进上下文,还可能让它按错误的步骤改数据。排除项是给路由划的那条负边界。
长度上我一般控制在两到四句,六十字到一百二十字之间。太短缺少区分度,太长会挤占索引预算,也会稀释关键词的权重——一段两百字的描述里,真正起作用的可能只有三个词组。
还有一个细节值得单独提:中英混写不要两边都写。有的描述写成「清洗 Excel 表格 / clean spreadsheet data」,看起来覆盖更广,实际会让关键词权重被摊薄,而且模型对两种语言的说法会分别匹配,反而更容易抢到不相干的请求。选定团队主要使用的语言写一遍,把用户可能出现的英文术语作为名词嵌在句子里,比整句翻译两遍更划算。
写完怎么验证?拿三十条真实请求,其中至少十条是不该触发的,人工标注意图,跑一遍路由,看混淆矩阵:
| 实际情况 | 触发了 | 没触发 |
|---|---|---|
| 该触发 | 命中,正常路径 | 漏触发,先补输入特征 |
| 不该触发 | 误触发,先补排除项 | 正常 |
误触发那一格要优先处理。改法通常不是加长描述,而是加一句「不用于……」,或者干脆把职责拆成两个 Skill,让边界更清楚。
五、三层披露的 token 账
渐进式披露这个词听着抽象,落到工程上就是三个加载时机。把三层的成本摊开算一遍,「为什么几十个 Skill 也撑得住」就不需要解释了。
| 层 | 内容 | 加载时机 | 单条成本 | 同时在场 |
|---|---|---|---|---|
| 第一层 | 名字 + description | 会话开始常驻 | 30~60 token | 全部 |
| 第二层 | SKILL.md 正文 |
路由命中后 | 600~1500 token | 一到两个 |
| 第三层 | 参考文档、脚本用法 | 正文明确指向时 | 2k~10k token 或 0 | 按需 |
算一笔具体的账。假设团队有四十个 Skill,索引平均每条五十 token,常驻成本是两千 token,占 200k 窗口的百分之一。如果换成「全量注入正文」,四十乘一千,就是四万 token,还没开始干活就吃掉两成窗口;更糟的是这四万里有三万九千是当下无关的内容,按上下文工程的规律,干扰项的密度一高,判断质量就下降。
再看一次真实请求的加载轨迹。用户说「帮我把这个月的对账表理一下」,第一层加载全部四十条索引,两千 token;路由命中 excel-data-cleaning,加载正文一千一百 token;正文第 1 步要求跑 inspect_excel.py,脚本源码零 token,回来的是一段两百 token 的 JSON;第 3 步发现表头映射有未命中的列,正文指向 reference/column-conventions.md,只读其中一节,八百 token。整场下来,技能相关的开销是四千一百 token,占总窗口百分之二。同一件事如果不用渐进式披露,光是四十份正文就要四万,而且模型还得在其中自己找出该看哪一份。
脚本这一层值得单独说。脚本的源码永远不进上下文,进去的只有「用途、参数、退出码」这三样。模型不知道 clean_excel.py 内部怎么实现,也不需要知道,它只要会拼命令行、会读 JSON 输出。这是渐进式披露里性价比最高的一层:计算发生在模型外面,只有结论回到模型里面。
三层结构能撑住几十个 Skill,靠的是成本结构的变化:从「N 份文档全量常驻」变成「一份索引常驻,加上命中那几份的正文」。前者随 Skill 数量线性增长,后者只随命中数量增长。所以真正需要控制的是索引规模,而不是 Skill 总数。
反过来说,三种做法会把这套结构毁掉。把所有正文拼成一个大 prompt 常驻,等于退回全量注入;正文写成五千字的教程,命中一次就吃掉半个窗口;参考文档里堆一堆模型永远用不上的历史案例,第三层就变成了负担而不是补充。
六、写好一份 Skill 的五条原则
步骤必须可执行。 每一步是一个动作加一条命令,或者一次明确的判断,不能是「分析数据质量」这种谁都能解释成任何意思的话。判断标准很简单:换一个人来读,能不能做出完全相同的动作。做不到就继续拆。
拿一句常见的写法对照。「检查数据是否有异常」这句话,十个人能做出十种操作:有人看空值,有人看离群点,有人看编码乱码。改成「统计每列空值比例,超过 5% 的列打印列名和前五行样例」,动作就唯一了。前者是愿望,后者是步骤,模型只能执行后者。
每一步都要有验证。 验证要能被观察到,最好是一个数字或一段结构化输出。比如清洗脚本输出 {"rows_in": 12043, "rows_out": 11980, "dropped": 63},紧接着一条断言:三者相加必须等于 12043。模型看到 11980 和 63 加起来对不上,就知道自己漏了什么;没有这条断言,它会直接进入下一步。
失败处理要分类。 我通常分三类:可重试的(文件被占用、网络超时)、需要修输入的(缺列、格式不符)、必须停下来问人的(业务规则冲突、主键不明确)。三类对应三种动作,写清楚,别让模型自己临场决定。模型最不擅长的就是判断「这个错误该不该继续」。
优先给脚本,而不是让模型现写。 让模型现场写清洗代码,等于每次都在没有测试的情况下上线一段新代码,而且这段代码的写法每次都不一样,出了问题无法复现。脚本是验证过的、有退出码的、行为固定的,模型只负责选参数和读结果。这一条对稳定性的贡献,比 prompt 里加十句「请小心」都大。
边界要写「不该做什么」。 前面提过,这里再强调一次,因为它是整份文档里最容易被省略的部分。人在写流程时习惯写 happy path,觉得边界是常识;对模型来说没有常识,只有文本。不写「不覆盖原文件」,它就真的会覆盖;不写「不猜业务含义」,它就会把「客户编号」和「订单号」合并成一列。
顺带一条长度经验:正文控制在一百五十行以内。超过这个长度,说明里面混进了本该放参考文档的细节,或者这个 Skill 承担了太多场景,该拆了。
七、边界:Skill、Prompt、工具、子 Agent
这四样东西经常被拿来互相替代,其实各自承载的东西完全不同。混用会让系统变得难以维护,也会让排查问题变得没有方向。
| 机制 | 承载什么 | 谁执行 | 加载方式 | 适合的场景 | 典型失效 |
|---|---|---|---|---|---|
| Prompt | 本次任务的意图与约束 | 模型 | 每轮常驻 | 一次性的特殊要求 | 越写越长,约束被稀释 |
| 工具 | 一个原子能力 | 程序 | 定义常驻 | 读写文件、调接口 | 描述含糊,参数乱填 |
| Skill | 多步流程与判断 | 模型读,程序做 | 按需加载 | 稳定重复的复杂流程 | 过期、误触发 |
| 子 Agent | 隔离的上下文与并行 | 独立的 Agent | 派生 | 大范围搜索、独立子任务 | 通信成本高,结论丢失 |
一句话区分:工具管「能不能做」,Skill 管「该怎么做」,子 Agent 管「在哪儿做」。
工具是能力的最小单位,它不该包含流程判断。一个 clean_excel.py 只负责执行清洗,不该决定「什么时候该清洗」;后者是 Skill 的事。反过来,Skill 也不该自己实现能力,它应该调用工具和脚本,而不是让模型用 Bash 现场拼一段 Python。
Skill 和 Prompt 最容易混。判断标准是复用次数乘出错代价:这个流程如果只在这个项目用一次,写进 prompt 就够了;如果每周都要用、错了要返工半天,那就值得做成 Skill。把一次性要求写成 Skill,维护成本立刻超过收益;把每周重复的流程塞进 prompt,等于每周重新交代一遍,还每次交代得不一样。
Skill 和子 Agent 是互补关系。Skill 的正文里完全可以写「用子 Agent 扫描整个仓库的调用点,只把结论带回来」,也可以写「所有文件操作必须通过 scripts 里的脚本,不要自己写代码」。前者解决上下文隔离,后者解决执行一致性,两者不冲突。
一个具体场景能把四者的分工说透:让 Agent 给一个老项目补测试。工具负责读文件、跑测试、写文件;Skill 写清「先读被测函数的调用点,再按现有测试的风格补三条用例,跑通之后才允许提交」;prompt 里交代这次的特殊要求「只补 billing 模块,别动其他目录」;子 Agent 被派去扫描全仓库的调用点,回来只给一份文件清单。四个机制各干各的,任何一个缺席,流程都会在某处变形:没有工具它动不了手,没有 Skill 它每次补的测试风格都不一样,没有 prompt 它会顺手改别的模块,没有子 Agent 它会把三十个文件的全文拖进主上下文。
八、Skill 是代码资产
这一点如果没建立共识,Skill 很快就会退化成「某个人电脑里的一个文件夹」。
我的做法是把 Skill 目录放进代码仓库,和业务代码同源、同分支、同一次评审。理由和把配置写进代码仓库一样:它会影响系统行为,就必须受版本控制。
新增一份 Skill,评审要看三件事:description 能不能准确路由、步骤有没有验证点、边界有没有写清。修改步骤,要附一次开/关对比的评测结果,哪怕只是三条用例。改脚本,走正常的代码评审,因为 scripts/ 里放的是可执行代码,不是文档。
版本管理上,SKILL.md 的头部加一个 version 字段,配一份 CHANGELOG.md。变更记录不要只写「优化了步骤」,要写清「为什么改」:是线上出了什么事故,还是业务口径变了。半年后回头看,只有「为什么」是有用的,「改了什么」看 diff 就知道。
有两类改动最容易引发回归,需要格外小心:触发条件的变化和边界的变化。前者会让原本不该加载的场景开始加载,后者会让原本被拦住的操作放行。这两处改完,必须重跑那三十条路由用例和危险操作用例。
团队共享时,目录分三层:个人层、团队层、组织层。同名 Skill 按显式优先级覆盖,不要依赖文件系统的扫描顺序。没有明确优先级,两个人各写一份 excel-data-cleaning,最后加载哪一份全看运气,排查起来非常痛苦。
反模式也很固定:Skill 放在个人 home 目录、靠口头传播;一份 Skill 服务五个部门,边界写成「通用场景」;改了脚本不改文档,模型按文档调用直接报参数错误,然后开始自由发挥。
九、怎么评估一份 Skill 有没有用
写完之后一定要做开/关对比,否则你无法区分「它真的有用」和「任务本来就简单」。
方法是控制变量:同一个任务、同一个模型、同一份初始上下文,开 Skill 跑五次,关 Skill 跑五次。五次是下限,因为采样有方差,跑一次得出的结论基本不可信。
| 指标 | 定义 | 采集方式 |
|---|---|---|
| 成功率 | 输出通过验收的比例 | 人工判定或断言 |
| 平均轮数 | 从开始到产出的工具调用轮数 | trace |
| token 消耗 | 输入加输出的总量 | trace |
| 人工介入 | 需要人纠偏的次数 | 会话记录 |
| 返工率 | 需要第二次修改的比例 | diff 统计 |
| 误触发率 | 不该加载时被加载的比例 | 路由日志 |
判据不需要很精细,看三个方向就够。成功率提升不到五个点、token 却涨了三成,不值。轮数明显下降、成功率持平,说明流程更顺,值得留。误触发率高,先改 description,别急着否定 Skill 本身。
有一个容易被忽略的事实:Skill 的收益主要体现在长尾失败上,而长尾在五次实验里未必出现。第一周跑得好好的,第三周遇到一张带合并单元格的表就崩了。所以评测集里必须包含历史事故样本,这些样本才是 Skill 真正要解决的问题。
负收益通常来自三种情况:Skill 正文太长,挤掉了关键上下文;description 抢了别的 Skill 的活,路由错乱;脚本和文档不一致,模型按文档调用报错,然后放弃流程开始自己发挥。这三种都不是「Skill 没用」,是「这份 Skill 没写好」,但结论往往被记成前者。
还有一件事要提前定:Skill 的退役标准。我的做法是看两个信号,连续两个月没有被正确触发,或者所在业务的流程已经改过一轮而它没跟着改。前者说明它解决的问题消失了,后者说明它已经过期。退役不是删文件,是在头部标 deprecated 并从索引里摘掉,保留半年再归档,因为总有人还在旧分支上用它。
评估脚本可以很朴素,能跑、能对比就够:
1 | def run_case(task, use_skill): |
十、常见的坑
- description 写成产品介绍。 「强大的表格处理能力」这种话对路由零贡献,模型需要的是触发条件和排除项。
- 正文写成教程。 讲了一堆为什么这么清洗,却没写先跑哪个脚本。模型读的是动作,不是原理。
- 步骤没有验证点。 模型做错了也照样往下走,最后交出一个看起来完整、实际全错的结果。
- 脚本靠自然语言约定参数。 「传入文件路径和主键」这种描述,模型会猜成位置参数、关键字参数、或者干脆自己写循环。
- 一份 Skill 覆盖太多场景。 条件分支写成 if/else 迷宫,模型读到第三层就迷路,最后只执行了第一条。
- 旧版本不删。 两份同名 Skill 同时存在,路由命中了过期的那份,改了半天没生效。
- 把内网地址、账号、密钥写进正文。 Skill 会被复制、被分享、被提交到仓库,这些信息一定会泄露。
- 只写 happy path。 边界和失败处理留空,等于把最容易出事的环节交给模型即兴发挥。
十一、检查清单
- 这个任务是否重复发生、流程是否稳定、错了代价是否够高?三条不满足就别做。
- description 是否同时写了「什么时候用」和「不用于什么」?
- 是否用了用户的口语说法,而不是内部术语?
- 每一步是否有可观察的期望输出或断言?
- 机械动作是否已经脚本化,脚本是否有明确的退出码约定?
- 失败是否分了「重试 / 修输入 / 问人」三类,并给了对应动作?
- 边界是否用否定句写清了「不要做什么」?
- Skill 是否进了仓库,有 owner、有版本号、有变更记录?
- 是否用三十条真实请求验证过触发准确率,误触发是否优先处理?
- 是否做过开/关对比,收益是否覆盖了维护成本?
Skill 的价值不在于让模型变聪明,而在于让结果变稳定。它把「这次能不能做对」从一个概率问题,变成一个执行问题:只要流程是对的、脚本是验证过的、检查点是可观察的,换哪个模型来跑,结果都不会差太远。真正花时间的部分从来不是写那几百字正文,而是想清楚每一步怎么验证、出错时该停还是该退。下一篇要讲的 Harness Engineering,处理的是同一件事的另一半:Skill 管的是「怎么做对」,Harness 管的是「做错了也出不去」。
系列大纲与全部篇目见:Agent 原理与开发。
延伸阅读
- 上下文窗口与上下文工程 —— 渐进式披露省下来的 token,到底省在哪儿。
- Harness Engineering —— 流程之外,用确定性程序给结果兜底。
