“skills”这个词最近在我本地的工作目录里出现得实在太频繁了。不管是Claude那边的SKILL.md，还是Cursor里越分越细的能力卡片，又或者自己用Agent框架时随手建的技能包，“把能力下沉成文件”这件事，正在快速取代过去那种在对话框里反复粘贴prompt的操作方式。这篇文章我想好好讲一次：一个名为skills的目录，到底该怎么从零搭起来，才能让Agent真的用起来、用得好，而不是变成一个落灰的Markdown仓库。
内容围绕的是通用技能体系设计方法，不绑定某个特定产品。我踩过的坑、反复改过的结构、最后沉淀下来的经验，都会直接写出来。适合正在折腾Agent工作流、或者感觉提示词已经撑不住复杂任务的开发者参考。
1. skills不是提示词仓库：先想清楚它到底解决什么问题
1.1 普通提示词的问题就出在“没有边界”
如果你往一个系统提示里塞过三十条工作规范，你一定会感觉到那种“说不上来哪里不对但模型就是在装傻”的体验。原因其实不复杂：大模型对超长指令的注意力是会稀释的，放在第15条的管理要求，很可能还不如用户随手补的一句话权重高。而skills体系的出现，本质上就是把长指令拆成一个个可以被按需加载的独立单元，让它只在对应场景里进入上下文。
这个区别很关键。普通的系统提示是“主机常驻内存”，无论用户聊什么你都得让模型想着；skills是“按需挂载”，只有任务特征匹配到某个技能才会加载它的说明。
我见过不少团队把“提示词工程”迁移成“技能工程”时，只是把原来的长提示词塞进一个叫SKILL.md的文件里，然后告诉自己“我已经用上技能体系了”。第一版我本人也这么干过，效果一般。原因很简单：技能文件最大的价值不是“内容换了个存放位置”，而是触发机制、使用流程、结束条件和参考素材被结构化地组织起来了。
1.2 Skills和普通文档的本质区别是“可执行”
一份普通的设计规范文档，模型读了之后能不能按规范干活？能，但效果极其不稳定。你最好还是每条都提醒它。而一份好的技能包，至少要包含四个要素：这个技能处理什么问题、它基于哪些方法论执行、它需要用户提供哪些必要信息、它完成时以什么格式输出。
我习惯把它们叫做技能四要素。缺了任何一个，技能包都会在使用中变形。
举一个很实际的例子。我之前给团队知识库机器人写过一个“新员工入职问答”技能包。最初里面只有一段FAQ和“请根据知识库回答新员工问题”这句话。实际跑起来之后，模型经常回答得太随性，把不该给的内部系统账号细节也贴出来。后来我把输出边界写进技能，明确规定“只输出可直接引用的文档链接和一句话结论；涉及账号权限时只提示找IT支持”，效果立刻稳定不少。
所以，skills目录不是用来存放知识的，它更像是给Agent准备的一份“操作手册加工具箱”。
2. 搭建技能目录：一个可用体系的文件结构长什么样
2.1 目录规范与命名约定
我的基本单元是一个目录放一个技能包，目录下至少有一份SKILL.md。整体结构大概是：
skills/ ├── code-review/ │ ├── SKILL.md │ ├── references/ │ │ └── review-checklist.md │ ├── scripts/ │ │ └── scan_for_todos.py │ └── examples/ │ └── before-after.md ├── meeting-minutes/ │ ├── SKILL.md │ └── templates/ └── incident-response/ ├── SKILL.md └── references/关于命名，我的原则是：用动词短语或明确的名词，不用含糊的形容词。code-review、incident-response这种一看就知道什么时候用的名字，比quality、best-practice这种强得多。后者看着很全面，实际触发时模型根本不知道它该不该被调用。
目录内部的文件排布也有讲究。SKILL.md必须放在技能包第一层，references放不会频繁改动的参考资料，scripts放可执行脚本或数据抽取逻辑，examples放给模型看的少量示例。这里有个常见误区：examples不是越多越好。放三五个足以说明输入输出形态的样例就好，放多了只会稀释模型对主指令的注意力。
2.2 SKILL.md的字段该怎么设计
SKILL.md的编写是这套体系的核心。我不建议把它写成自由格式散文，应该用带元信息的结构化格式。下面是我目前比较稳定的模板：
--- name: code-review description: 对指定目录中的代码提交进行逐文件评审 version: 1.2.0 when_to_use: 用户要求检查代码、Review MR/PR、或让AI检查提交前问题 tags: [code-review, qa, lint] --- ## 执行步骤 1. 确认目标代码路径或本次变更文件列表 2. 调用references/checklist.md中的检查项 3. 输出问题列表，按阻塞/建议分类 ## 输出格式 - 阻塞问题：文件路径、行号、原因、修改建议 - 建议问题：文件路径、行号、说明、可选方案 - 无权访问的文件，明确标出未检查 ## 边界 - 不修改代码，除非用户明确要求生成diff - 不评审无意义的格式改动重点关注几个字段。description要能被模型用来做匹配，建议写成“当用户想要X时使用”；when_to_use更直白一些，直接列举触发场景。version很重要，因为技能会迭代，没有版本号，出了问题你都不知道是哪一版逻辑导致的。
还有一个我自己习惯加的字段：must_avoid。它用来告诉模型“这个技能不要做什么”。比如知识问答技能里我写的是“不要编造不存在的文章链接”。这个字段对控制模型行为非常有效，效果不亚于正向指令。
2.3 参考资料和脚本怎么跟主文件配合
SKILL.md主文件最好保持在三百行以内，太长了模型反而不容易抓住重点。复杂的方法细节放references目录，需要计算或批处理的部分放scripts目录。
举个例子，我给“会议纪要”技能放了一个templates/meeting-notes.md模板，SKILL.md里只写“按模板输出纪要”，模板本身放在references里。这样主文件干净，模型执行时又能拿到完整的格式约束。
脚本的情况类似。写过一个“统计代码行变化”的脚本，SKILL.md里只声明“调用scripts/diff_stats.py生成统计”，并不把代码贴进主文件。脚本编写本身就是独立小工程，优点是技能可以复用Shell能力和外部工具，缺点是你要保证脚本在目标机器上能跑。如果你生成的技能包要给别人用，脚本的跨平台性就一定不能忽视，路径分隔符、依赖库版本这些细节都会成为隐藏炸弹。
3. 触发与执行：让模型在合适时机主动使用技能
3.1 把when_to_use写得像行为特征而不是语义词汇
模型判断该不该用某个技能，靠的不是人类阅读后理解出的“这个领域相关”，而是描述里的行为线索。所以when_to_use里我几乎不用“如果用户需要代码质量评估”这种话，我会写“如果用户要求做Code Review、检查提交、评审MR/PR或让AI找代码里的bug”。
行为化描述的好处是，模型在推理时更容易匹配上具体动作。光是“代码质量”这个词，可能匹配到优化建议、架构调整、静态扫描等多种意图；但“检查提交”“评审MR/PR”这种动作词，指向性就明确得多。
我后来做了一次A/B测试，同一个技能分别用两种风格的when_to_use去跑同样的评审请求。结果行为化描述的那一版，触发率高了接近三成。触发这步做不好，后面技能内容写得多精细都没用，因为模型压根不会翻开这个文件。
3.2 技能内部的状态约定：调用中、完成、失败
很多人写技能是从执行步骤直接跳到输出，中间缺了一个状态约定。实际上，技能在执行过程中会遇到各种意外：用户给出了不完整信息、依赖的脚本报错、目标路径不存在。如果技能文件里不写这些情况的处理方式，模型就会自己即兴发挥，最常见的结果就是编造一个看似合理的输出。
我的做法是在SKILL.md中显式定义三类状态：
- 正常完成：按输出格式返回分析结果
- 输入缺失：列出需要用户补充的信息，逐项询问
- 执行失败：说明失败的操作和原因，给出备选方案（比如改用人工确认）
这样不管环境怎么变化，模型至少知道自己的输出边界。对生产环境来说，稳定比聪明重要得多。
3.3 召回测试：如何确认技能真的会被触发
这一节直接给操作路径。搭建完技能之后，我建议立刻跑一遍召回测试，而不是直接上线。做法是：
- 准备十个不同的用户请求，覆盖面要广，一半是明确命中场景，一半是模糊边界场景
- 在干净的会话里逐条发出，观察模型是否加载并使用该技能
- 检查哪些请求被漏掉，回头修改when_to_use
- 检查哪些请求被误触发，收紧description描述
这个过程通常要重复三轮以上才能稳定。我电脑上至今还保留着一份recall_test_cases.md，里面记录了每个技能的测试用例和结果，因为技能文件更新后，原本能触发的场景可能因为措辞改动反而失灵，回归测试是这玩意的保险栓。
4. 进阶玩法：技能的组合、版本管理和多项目复用
4.1 用Git管技能，记录“为什么改”
技能文件的生命力在迭代，迭代就必须有记录。我把整个skills目录做成独立仓库，每个技能作为目录独立演进。提交信息里我会写清楚改了什么和为什么，比如“在边界字段中禁止生成未经验证的链接——线上出现过一次幻觉”。
一方面，这能让你回滚到任何一个历史版本；另一方面，当Agent突然行为异常时，你能准确判断是不是一次技能变更导致的。
版本号管理我用的是语义化版本习惯：主版本号在技能操作流程变更时增加，次版本号在边界和细节调整时增加，补丁号对应错别字或小修小补。虽然听起来有点工程化，但多技能并存之后你会发现：没有版本概念，根本没法做对比分析。
4.2 组合技能的三种模式
单个技能解决单类问题，真实业务往往是多类问题的组合。我总结过三种稳定的组合模式。
- 顺序流水线模式：前一个技能的输出直接作为后一个技能的输入。比如“日志分析”产出异常清单后，自动接“故障定位”技能。
- 父子依赖模式：外部技能包只声明依赖某个基础技能，基础技能提供公共工具函数或统一输出模板。
- 条件分支模式：根据用户请求的性质判断走哪个子技能路线。比如“代码相关请求”进入评审或修复分支，“文档相关请求”进入总结或翻译分支。
第三种模式实现起来最复杂，需要在SKILL.md里定义清晰的分流判断条件。我的建议是别贪快，先把顺序模式和父子模式用熟，分支模式真的有必要再上。
4.3 跨项目同步与灰度验证
同一个技能会被多个项目复用，这时候最怕的是“改了一个项目里的技能，其他项目还是老版”。我的做法是用git submodule或独立的技能包目录进行多项目引用，统一从技能仓库分发。
分发之前要做灰度。道理和发版一样，技能改动先在自己搭的测试环境里跑几天，确认没有明显劣化，再同步到全部项目。如果同步之后发现某个特定项目的上下文比较容易误触发，就单独为它加一条上下文规则做减法。
灰度验证时的指标我放在后面专门讲，这里先记住一个关键原则：技能改动必须视为代码变更，不能当作文本润色来对待。
5. 一二线实操中常见的坑：skills目录是怎么变成垃圾场的
5.1 排查“技能没生效”的完整链路
技能没有生效的原因，按我的经验，出现频率从高到低排列如下：
- when_to_use写得过于模糊，模型认为当前场景不匹配
- 技能被其他系统指令遮挡，模型选择了另外的执行路径
- SKILL.md中的步骤互相矛盾，导致执行中自行中断
- 引用文件路径写错，模型读不到references里的内容却仍然硬编
排查的时候别上来就改SKILL.md里的正文描述。我自己的调试顺序是：
- 第一，打开调试信息或让Agent自述当前执行计划，看它到底有没有加载这个技能
- 第二，如果加载了但没照做，检查执行步骤是否与环境实际能力匹配，比如要求调用一个不存在的脚本
- 第三，如果没加载，检查when_to_use与用户请求的语义距离，把用户实际说的话原样贴到测试用例里跑一遍
- 第四，检查是否有更早加载的其他技能“抢占”了语境
这四步走完，绝大部分问题都能定位到具体环节。
5.2 过封装、字段冲突、引用失效的处置经验
你可能会觉得技能写得越细越好，但实际上有一种症状特别典型：技能文件越写越长，执行反而越来越飘。因为它内部塞了大量“如果……那么……”的分支，模型在长上下文推理时容易顾此失彼。
我的约束是：单技能SKILL.md不超过三百行，步骤不超过七个。超过就要拆分子技能或把细节挪进references。
字段冲突也值得提一嘴。我在一个项目里同时挂了“知识问答”和“信息检索”两个技能，description高度相似，模型几乎每次一遇到信息获取请求就随机选一个。解决方式是把知识问答改名为“内部wiki知识问答”，明确限定它只在知识库检索时使用；信息检索则改为“跨平台网络资源搜索工具”，两个场景瞬间就分开了。
引用失效是另一种常见坑。技能里引用的文档挪了位置，SKILL.md里的相对路径就没更新。模型读不到材料，又不想承认失败，就开始靠记忆硬撑。解决办法说起来简单：每次移动文件后全局跑一遍链接检查脚本。
5.3 小心“技能幻觉”和过度自信
最后一个坑是心理层面的。你搭好了十来个技能包，每层都有模有样，很容易产生“我的Agent已经很强了”的错觉。但技能文件本质上还是给模型看的文字，模型没有真正理解技能背后的业务逻辑，只是被instruction带着走。
我曾经遇到过几次技能输出看起来很专业、但稍微对一眼源数据就发现完全对不上的情况。结论还是那句老话：技能解决的问题边界一定要清晰，超出边界时要允许它向用户说明“该场景超出我的技能范围”，而不是硬着头皮生成一份貌似合理的废话。
6. 我用真实失败案例驱动迭代的做法和一组观测指标
6.1 从故障报告反推技能更新清单
我维护技能的方式，与其说是“定期复盘”，不如说是“让事故来敲打”。只要线上出现一次错误输出，我就整理一份故障记录，包含：用户请求原文、模型错误输出、期望输出、根因判断、需要改哪个技能字段。
这个故障报告文件就是下一轮迭代的清单。技能不是凭感觉去优化的，而是根据已知失败来逐个击破的。做得久了你会发现，大部分技能问题不是发生在日常顺手的地方，恰恰是那些“你怎么问它都不会出错”的边界情况。
举一个真实故障：有一次知识库机器人把一篇内部未发布计划的标题直接输出给了外部提问者。根因是技能里没有定义“未发布文档”的处理策略。我就在SKILL.md的must_avoid字段下加了一条“不要输出状态为草稿或未发布的文档内容”，并在references里补充了一套可见度分级规则。之后再没出现过同类问题。
6.2 可量化的几项指标
衡量技能效果，我所在的团队目前会采集这几项数据：
| 指标 | 计算方法 | 目标 |
|---|---|---|
| 触发准确率 | 正确触发次数 / 应触发次数 | ≥ 90% |
| 错误输出率 | 产生幻觉或错误信息次数 / 调用次数 | ≤ 5% |
| 无效调用占比 | 调用了但输出对用户无用的比例 | ≤ 15% |
| 技能间冲突数 | 两个及以上技能同时被触发且输出打架的次数 | 降为0 |
这些指标不需要专门搭建平台，简单统计就能用。重点是让每个技能的变化都能收到反馈。一个技能改了，跑一个月的调用数据，触发率有没有提升，错误率有没有下降，数据比感觉可靠得多。
6.3 写到最后：技能目录的定位永远是“边学边改的活文档”
“skills”最终长成什么样，没有一个标准答案。我的经验是保持目录结构稳定、触发描述行为化、迭代靠故障数据驱动，同时克制地控制单个技能的范围和长度。
我不打算写一个完美的终极技能模板，因为我知道下一周遇到新问题，我又会往某个SKILL.md里加一条边界规则。构建技能体系这件事，本质上就是持续整理你和模型协作之间的相处规则。每多一条规则，Agent就多一分可靠。
如果看完这篇你准备动手清理自己的skills目录，我的建议是先做两件事：检查所有技能的when_to_use是不是行为化描述；把每个SKILL.md的版本号补上。剩下的，等跑出真实数据再滚动迭代。
