大模型技能库实战：从零搭建可复用、可测试的Agent能力包

朋友最近问我一件事：你那个叫“skills”的项目，到底在做什么？我想了想，给了个有点绕的回答——我是在把大模型从“会做”变成“做得稳”。这个词现在在Agent圈子里被反复提起，但我发现很多人对它的理解还停留在“给模型写个更长的prompt”或者“挂几个function上去”。真正把skills做成一整套可落地的能力包体系，其实要解决的问题远比想象中多。这篇文章把我从零搭建这套技能库的全过程、结构设计和踩坑经验完整拆出来，适合正在做Agent应用、想摆脱“每次让模型干活都要现场调prompt”的开发者参考。

1. 从“写完就忘”到“越用越强”：我为什么要做一套技能库

1.1 问题出在“发挥不稳定”，而不是“不会做”

去年下半年我开始做自己的自动化工作流，一开始用的是最朴素的长prompt方案：把所有需求、约束、示例一股脑塞给模型，让它按部就班地干活。结果就遇到了所有做Agent的人都会撞上的那堵墙——模型确实“会做”，但发挥极不稳定。

同一套任务，早上执行的时候它逻辑清晰、格式工整；到了下午同样的输入，它可能突然用了一种完全不同的表述方式，或者跳过中间一个关键判断，直接给出一个看起来对但实际上没经过校验的结论。

这个现象让我意识到一件事：模型的能力是存在的，但它没有被“结构化地固化”下来。就好比一个能力很强的新员工，你口头跟他说了一遍工作流程，他听懂了，明天也能做，但你没法保证他每一次都按同一个标准执行，更没法保证他下个月还能记得你昨天补充的那个细节。你需要的是给他写一份标准作业程序（SOP）。

给模型用的SOP，就是skills。它的核心不是“告诉模型做什么”，而是把“怎么做、按什么标准做、遇到什么情况怎么办”固化成一套可复用、可版本管理、可测试的能力包。

1.2 Skills和Tools、MCP、长Prompt到底有什么区别

做技术选型的时候，团队里最容易出现概念混淆。我简单用一个表格说明我在实际开发里对这几样东西的划分方式：

关键区别在最后一格：Skills不是工具的替代品，它是工具之上的一层“方法层”。一个skill里面可以调用多个tool，也可以不调用任何tool，只靠结构化的思考流程就能完成判断型任务。它同时承载了“该怎么做”和“为什么这么做”的知识。

我用了一个类比来跟朋友解释：Tools是工具箱里的扳手和螺丝刀，MCP是工具箱的统一接口标准，而Skills是一本设备维修手册。维修工当然需要扳手，但他更需要知道先拆哪颗螺丝、怎么判断故障、哪一个步骤最容易出错——这些只有手册能提供。

1.3 技能库设计的三个底层原则

在整个项目推进过程中，我给自己定了三条原则，后续的每一个设计决策都是围绕它们展开的：

第一，确定性优先于灵活性。模型天然擅长发散，skill要做的是在关键节点上“收”。凡是能用脚本、模板、规则确定下来的步骤，就不应该留给模型自由发挥。第二，可测试才能可维护。一个技能如果没法自动化验证输出质量，那它本质上仍然是prompt，只是换了个包装。第三，渐进式积累。不需要一开始就设计几十个技能，先从一个高频任务开始，跑通后再复制方法论。

这三条原则影响了后面所有的设计决策。尤其是第一条，直接决定了我在技能包里放脚本而不是纯文本的根本原因——脚本是确定性最强的载体。

2. 给技能建个“家”：完整可复用的技能库目录结构

2.1 顶层划分与命名规范：让技能库半年后还能看懂

先看我现在在用的目录结构，这是在多次重构之后定下来的模式：

skills/ ├── common/ # 跨技能共享的公共资源 │ ├── scripts/ # 公共脚本，如校验工具、格式化工具 │ └── templates/ # 公共模板，如报告骨架、邮件模板 ├── weekly-report/ # 单个技能的根目录，名称必须精确 │ ├── SKILL.md # 技能说明书，模型和人类都靠它理解 │ ├── scripts/ # 该技能专用的脚本 │ ├── assets/ # 参考资源，如示例报告、数据字典 │ ├── examples/ # 输入输出示例，模型的最佳参照系 │ └── tests/ # 自动化测试用例和测试夹具 └── contact-summary/ ├── SKILL.md ├── scripts/ └── examples/

顶层目录的命名是我的第一条纪律：目录名就是技能的身份证，必须是动词短语，必须精确描述这个技能做什么，不许用泛化的名词。比如我实际项目里就踩过一个坑，最早给“联系人信息整理”这个技能取名为contact。结果模型在用户问“帮我整理一下这周见过的客户”时压根没调用它，因为从名字上看contact更像一个名词条目，而不是一项操作。后来改成contact-summary，调用率立刻上去了。

命名规范定了两条： 一是动宾结构，如weekly-report、summarize-article，而不是article、report； 二是不超过三个单词，太长会让模型在技能选择时产生语义漂移，太短则边界不清。

2.2 SKILL.md：一份人类和模型共同依赖的技能说明书

每个技能目录的根部放一个SKILL.md，这是整个技能包的核心文件。我先给出一个我现在实际使用的周报整理技能的SKILL.md骨架，后面再逐步解释为什么每块都是必要的：

--- name: weekly-report description: 根据一周的零散工作记录生成结构化周报。仅在用户提供多段原始记录、且需要汇总汇报时使用。不要用于单个任务的简单回答。 --- # 周报整理技能 ## When to Use - 用户给出多条工作记录，要求整理成周报 - 需要按“项目/任务/成果/问题”四个维度分类汇总 ## What It Does 1. 提取原始记录中的时间、任务、责任人 2. 将每条记录映射到项目维度 3. 合并同类项，去除重复内容 4. 按指定格式输出结构化周报 ## Workflow 1. 读取用户输入，识别记录条数。少于3条时不启用本技能 2. 调用 `scripts/parse_notes.py` 解析原始文本 3. 调用 `scripts/map_projects.py` 做项目归类 4. 人工确认关键字段后输出 ## Output Format - 表格形式，列：项目/任务/成果/问题/下一步 - 必须遵守 `assets/report_template.md` 的骨架结构 ## Examples - 见 `examples/input_01.txt` 和 `examples/output_01.md` ## Troubleshooting - 如果输入文本没有明确时间信息，默认以当前周为时间窗口 - 如果分类置信度低于0.7，将该条放入“待确认为其他”

你可能注意到了，SKILL.md里面有大量“不做什么”的描述。这是我在实际使用中最重要的一条经验：技能说明必须同时定义“使用边界”。模型在决定是否调用一个技能时，靠的就是description字段做语义匹配。你写得越模糊，它就越容易在不该用的时候调用，或者在该用的时候不调用。

我在description里写“仅在...时使用，不要用于...”，本质上是在教模型区分“这个技能的适用语境”和“其他任务的语境”。这个字段是技能库的门卫，它写不好，后面全白搭。

2.3 scripts和assets：把“自由发挥”压缩到最小空间

SKILL.md再详细，它也只是文本，模型执行的时候仍然可能偏离。我把所有能确定化的逻辑全部下沉到脚本里，这是我在前面提到的第一条原则的具体落点。

以周报技能为例：

• parse_notes.py负责把用户的原始记录切成结构化条目，这一步完全不需要模型做判断，用正则和分词就能完成；
• map_projects.py负责把条目映射到不同的项目类别，这一步我做了两版，第一版用规则匹配，后来发现准确率不够，改成了本地小模型分类，但无论用哪种方案，决策权都在代码里，不在模型的自由发挥里。

assets目录放的是“参考物”。模型在生成周报时，如果只看Workflow里的文字描述，仍然可能写出不同风格的报告。但如果你给它一个已经做好的示例模板，它会按着模板的骨架走。assets/report_template.md放了一份我亲手写的标准周报，加了大量注释说明“这里为什么这么写”，相当于给模型提供了强力的格式锚点。

这里有个容易被忽略的点：assets里的参考文件，其质量直接影响输出质量。如果模板本身写得含糊，模型只会依样画葫芦地含糊。所以我在模板里连“汇报对象”这种字段都给了两种写法（对内、对外），让模型有据可依。

2.4 examples与tests：能力包的“练习册”和“体检报告”

examples目录放的是真实的输入输出对，每个技能至少要有2到3组，而且必须覆盖“典型情况”和“边界情况”。以周报技能为例：

• 第一组是常见的3条记录输入，输出一份正常周报；
• 第二组是不足3条记录，看技能如何处理边界；
• 第三组是超过20条记录的批量输入，看分类和去重逻辑是否还在线。

这些示例不光是给模型参考的，更是我写自动化测试的基础。tests目录里放的是基于pytest的测试脚本，逻辑是把examples里的输入喂给技能，然后校验输出是否符合SKILL.md里定义的格式约束。后面我会专门讲测试这一块怎么设计。

3. 从零写一个技能包：以“批量整理周报”为完整实操案例

3.1 动手之前先写“能力边界声明”

我在开发新技能时有个固定动作：先不写任何代码，先用三句话写下这个技能的边界声明。一句话说明它在什么场景下使用；一句话说明它输出什么；一句话明确“它不做什么”。

周报技能的三句话是：

• 场景：用户提供多条零散工作记录，需要汇总成结构化周报；
• 输出：包含项目、任务、成果、问题、下一步的标准周报表格；
• 边界：不接受无记录输入；不处理单个任务的详细展开；不生成超出所给记录范围的新内容。

为什么这一步这么重要？因为我在项目实践中发现，大多数技能失效，都不是代码写错了，而是边界没写清。模型把技能用到了错误的场景里，然后你看着输出觉得“不对劲”，但说不清是哪里的问题。边界声明就是把这种模糊的“不对劲”变成一个可验证的、明确的约束。后期写测试用例时，边界声明里的每一条都能转化成一个负向测试。

3.2 编写SKILL.md的步骤序列：先流程后格式再异常

我写SKILL.md不是一次成型，而是按固定的顺序逐块填充：

第一步，写“What It Does”，列出技能执行的完整步骤序列，但要刻意保持抽象，不要在这一步写任何具体格式。我在这一块写的都是“提取时间、任务、责任人”“映射到项目维度”这类操作描述，因为它们定义了技能的“动作清单”。

第二步，写“Output Format”和assets模板。这一步的价值是定义“合格输出”的客观标准。我把周报模板细化到了字段级别，包括字段名、顺序、必填可选、对齐方式，甚至表格里的标点符号规范。一个技能的输出格式越具体，自动化验证时越容易写断言。

第三步，写“Workflow”。很多人会把这一步和第一步混在一起，但我刻意做了一个分层：第一步说“做哪些事”，这一步说“每一步用什么工具、谁来做”。Workflow里明确标注了哪些步骤要调用scripts/下的哪个脚本，哪些步骤要由模型自行判断。这么做的目的是让模型知道“哪个环节没有自由发挥空间，哪个环节需要它的推理能力”。

第四步补Examples和Troubleshooting。这一块的价值在你遇到一次真实的执行失败后会深刻体会到——你不需要再靠猜来调试，而是可以直接在Troubleshooting里给模型预设兜底方案。比如我写过“如果输入文本没有明确时间信息，默认以当前周为时间窗口”，这就是从一次记录缺失时间的失败案例里沉淀出来的。

3.3 脚本封装：把判断逻辑从模型脑子里挖出来

周报技能里最有代表性的脚本设计是map_projects.py的版本演进。最初一版我用的是硬编码关键词匹配，比如“客户端”“联调”映射到“交付项目A”，但很快发现自然语言表达太灵活，用户写“和客户对了一下进度”两句都拿不到关键词。

后来我改成了一条混合策略：脚本里先用规则匹配，把明显能确定的记录挑出来；剩下模棱两可的少量记录再交给模型做分类。这个设计的巧妙之处在于：明确的部分确定性极高，不需要消耗模型；模糊的部分总量很少，留给模型也不容易出错。

这一版改完后，周报技能的稳定性一下子提升了一个档次，原因很简单——你把90%的确定性工作从“模型思考”里拿掉了，留给模型的只剩下它真正擅长的语义理解部分。这也是我给其他开发者的核心建议：凡是可以用代码实现的功能，就不要让模型靠“想”来完成。

3.4 本地跑通十连测：不压测的技能等于没写

技能写完后，我不会直接放心让它上线执行，而是先跑一个“十连测”。具体方法是：准备10份不同的输入（包括正常输入、边界输入、故意缺失信息的输入），让技能连续处理10次，每次我都检查输出是否满足SKILL.md里定义的约束。

这个环节极其重要，因为它测的是“稳定性”，不是“会不会”。大模型有一个特点，你让它做一次，它大概率能做好；但如果你让它连续做10次，它可能有一两次发挥失常。而十连测的价值恰恰在于暴露这个“失常率”。如果一个技能10次中有1次输出偏离了格式模板，我会回头检查SKILL.md的描述是不是有歧义，或者模板里的示例是不是不够明确。这比每次都靠人工review输出高效得多。

有一次我在十连测里发现，模型连续5次都在“问题”一栏里写“暂无”，但原始记录中明明有一条提到了风险。排查后发现是assets模板里的示例周报把“问题”栏写成了“暂无”，模型把这个当成了默认值。修改模板、补充一个带风险的例子后，这个问题彻底消失。这种问题，光靠prompt工程是发现不了的，必须靠实测压测。

4. 技能不是写完就完：回归测试、版本管理与“技能森林”的互相干扰

4.1 为什么聪明的模型也会“漂移”：给技能做回归测试的必要性

先解释我标题里说的“漂移”。大模型服务在持续迭代，它的语言风格、对指令的服从度、甚至对结构化输出的偏好都会悄悄变化。你可能遇到这样的情况：同一个技能，上个月每次都正确调用脚本，这个月突然有几次不调用，而是自己“脑补”了一个输出。模型没有变笨，它只是换了推理路径。

这给我的教训是：技能库是一个需要持续维护的资产，它的质量会随着底层模型的变化而变化。我后来学会了每次升级模型版本时，把所有技能的测试用例整体跑一遍。第一次跑就发现了问题：周报技能里原本能正常调用的parse_notes.py，在新模型版本下被直接跳过了，模型（当时用的是某主流大模型）选择自己解析后直接输出。因为SKILL.md的Workflow里写的是“调用脚本解析”，但模型觉得它自己也能解析，就选择了更便捷的路径。

4.2 用回归测试把“模型的选择”拉回正轨

针对上面这个问题，我做的第一件事是加强SKILL.md中的表述，把“调用 scripts/parse_notes.py”改成了“必须调用脚本，禁止直接解析原始文本”。但光靠嘴上强调不够，我同时写了自动化回归测试。

回归测试的核心思路是：用一个测试驱动框架（目前用的是pytest）读取tests目录下的用例，通过API让模型执行技能，然后自动比对输出。我设计了几个固定的断言模式：

• 格式断言：输出是否包含指定字段，是否符合模板结构；
• 稳定断言：同一个输入执行3次，结果是否一致；
• 调用断言：技能是否按预期调用了scripts/下的脚本（这个需要一点埋点手段，在脚本出入口打印日志）；
• 负向断言：当输入不属于该技能适用范围时，是否正确地拒绝执行。

其中“调用断言”最关键，因为它是唯一能直接证明确实走了“脚本路线”而不是“模型自由发挥路线”的测试。第一次跑通这组断言时，我才真正敢说这个技能是“固化了方法论”，而不是“碰巧输出正确”。

4.3 用版本描述记录能力边界，避免技能悄悄“膨胀”

技能库用得越久，越容易出现一个隐蔽的问题：技能膨胀。起因通常是某个技能在使用过程中发现了一个缺口，于是你顺手在SKILL.md里加了一段新功能描述。几次迭代下来，一个本来是“生成周报”的技能，慢慢变成了“生成周报+日程提醒+任务分配+项目复盘”。

膨胀的坏处是：模型在技能选择阶段会变得困惑——它看到description里包含太多能力，就无法判断当前任务到底该不该调用这个技能。更糟的是，一个技能内的步骤序列越来越长，模型在中途偏离的风险也越来越大。

我的应对方式是在每次修改技能时强制更新一个version字段和一段简短的“变更说明”，并在变更说明里同时写“这次加了什么能力”和“什么情况下仍然不要用这个技能”。这个做法相当于给技能做“瘦身记录”。后来我养成了一个习惯：如果某个技能的能力点超过了4个，就会考虑拆分成两个技能。某次我把“数据汇总”类技能从5个能力点拆成weekly-report和project-analysis后，两者各自的调用准确率都明显上升，这验证了“越小越好用”的判断。

4.4 技能森林效应：公共资源目录与共享依赖的管理

当技能数量从几个增长到十几个，它们之间就会出现共享依赖的问题。很多技能用同一个校验脚本、同一份格式模板，如果每个技能目录里都复制一份，维护成本会迅速失控。我后来引入了common/目录，把所有跨技能复用的东西都放进去。

一开始我只把common/scripts里的公共脚本抽象出来了，但马上遇到了新问题：某个技能在测试时因为common/目录路径写错导致脚本没被调用。后来我干脆定了一条规则：任何技能目录内的脚本涉及公共逻辑，引用路径必须以common/开头，并且回归测试里额外加了一条“资源是否存在”的静态检查。这条规则救了后来无数次升级公共脚本的命——因为只要我改了common/scripts/validate.py，所有依赖它的技能在下一次回归测试里都会收到验证结果，而不需要我挨个去检查。

依赖管理这个事，在技能数量少的时候完全无感，等到技能多了，忽略它必然出问题。我的感受是在第十个技能左右时出现了一次“连锁崩”——改了一个公共模板，结果三个技能的输出格式全变了。从那以后，公共资源的改动一定会触发全库回归。

5. 真正上线使用时踩过的坑：命名、幻觉、过期知识与成本

5.1 名字模糊的代价：该调的技能不调，不该调的乱调

我在前面提到过contact这个命名失败的例子，它在实际运行里带来的后果远超我的预期。一个语义模糊的技能名，除了调用率低之外，还带来了另一个问题：某个用户问“帮我发一封问候邮件”，系统没有选择合适的技能，反而因为contact目录下有联系方式模板，调用了这个技能，模型编了一段基于模板的联系人维护建议。

这个错误让我意识到，技能的选择阶段本质上是“语义匹配”问题，而匹配的基础就是从目录名和description里抽取出来的一组关键词。如果关键词系统本身就包含歧义，下游的模型再怎么优化也拉不回来。我给你的建议是：建立技能库时，先列出所有技能的“动词短语名”，把语义词义相近的全部放到一起审视，如果两个技能的名字在语义上重叠度很高，就要么合并，要么把其中一个的表述改得更精准。

5.2 技能文档太长，模型会“读不到重点”

多数人以为给模型的说明写得越详细，执行就越精准。我在实践中发现了一个反直觉的现象：当SKILL.md的长度超过一定阈值后，执行稳定性反而开始下降。我推测原因和模型的注意力机制有关——当一份文档里塞满了细节，模型会平均分配注意力，无法聚焦在关键的“必须做”和“禁止做”上。

有一次我在给联系人总结技能补了一长段“背景信息”后，回归测试里格式字段的保持率从100%掉到了80%。排查了半天，最终发现是新增的背景段落里提到了一种旧的输出“作为XML”，而模型把“XML”当成了新的输出格式，导致输出结构直接崩掉。

我现在的做法是遵循“一切从简”原则，在SKILL.md里，凡是不能直接指导当前执行行为的内容一律不放。背景信息如果确实要写，放到assets目录下单独一份文档里，并且不在主流程中提及。一个可参考的尺度是：SKILL.md的描述部分建议控制在2000字内，超过就说明你是时候把里面的一部分内容抽到assets里了。

5.3 过期知识固化：技能里的“旧世界”

技能把知识固化下来了，这是它的优点，同时也是潜在风险。我的项目里出过一次很典型的教训：某一次我为“部署检查”技能写了详细的POST请求格式，并在模板里写了一个旧版本的API地址。两个月后，服务端接口升级，返回结构变了，但这个技能依然按旧版本的格式解析返回结果，导致每次实际执行都会报错。

这个问题比命名模糊还隐蔽，因为它不是“模棱两可”，而是“稳定地错”。模型不会自动去怀疑一个技能里写在SKILL.md中的接口路径是否仍然有效，因为它默认技能里的知识就是正确的。

我的应对方案是给技能加了一个“知识创建时间”字段，并且对涉及外部接口、库版本这类强时效性知识的技能，额外写了一条“定期更新提醒”的命令。更关键的是一种平常心：你设计技能库时，要默认“外部世界是会变的”，而不是“外部世界是稳定的”。凡是涉及外部依赖的技能，都要预留出“依赖可能过期”这种状态的检查机制，哪怕只是简单的版本号校验。

5.4 成本与延迟：技能不是“越多越好”

这是最容易被忽视、最后受教训最深的坑。技能包越大，模型在“选择技能”这个阶段消耗的token就越多，因为每一次任务都要把所有技能的description读完才能做筛选。我早期的技能库有30多个技能，每次请求光技能选择副作用的token开销就占了总token的20%左右，延迟也肉眼可见地增加。

后来我做了一次大的减法：把低频技能移出主库，只保留一个精简的核心技能集（8个），其余全部收进“按需加载”的二级目录。执行频率最高的任务，默认只看标题技能集，搜索后再将候选技能动态接入。这个结构调整是性能上升的最直接原因。同时我也把每个技能的description字数压缩到了极限，只保留“何时用、何时不用、核心输入输出”，把详细说明全部移到正文里。如果你发现技能库越用越“沉”，不妨从这个角度审视：你的系统每次都要为“选技能”这件事额外付出多少成本？如果这一项占比过高，削减技能描述和技能数量几乎是立竿见影的优化。

6. 结尾：一点真实的个人体会

技能库这套东西，做起来比看起来更考验工程习惯，而不只是写prompt的水平。它本质上是把“模型上一次做对了”这件事从偶然变成必然，再把“必然”变成资产。

我现在的新项目里，最开始就往这个方向搭：新需求先不急着写大prompt，先问自己“这个能力能不能拆成一个技能，它的边界在哪，测试怎么做”。这句话值得印在工位上提醒每一个做Agent的人。最后再分享一个小技巧：每个技能都要有两个“不”字开头的描述——不做边界外的事、不做确定性以外的事。这两个“不”字，比一千个“要”字更管用。