做AI Agent开发的人，最近绕不开的一个词就是“agent-skills”。我一开始看到这两个词的时候觉得没什么稀奇，Agent能调工具、能写代码、能搜网页，不早就实现了嘛。但真正动手做下来才发现，把单个能力串成一个“技能包”，和零散地给Agent接几个API，完全是两码事。项目标题叫“agent-skills”，本质上就是做一个面向Agent的能力封装层——让模型不只是“会调用函数”，而是“知道在什么场景下、用哪一组工具、按什么顺序去完成一个完整任务”。
这篇文章我用自己的一个真实项目来讲。会拆解一个Agent技能包应该长什么样、内部怎么组织、参数怎么设计、验证怎么落地，然后给出一套可以直接参考的实现方案。适合正在做Agent应用、被“工具越来越多但效果越来越差”困扰的开发者，也适合刚接触Agent开发、想搞清楚“Skills和普通Function Calling到底有什么区别”的朋友。
1. 先拆清楚：Agent Skills到底是什么
1.1 从Function Calling到Skills，差的不只是名字
很多人第一次接触Agent开发，是从Function Calling入门的。给模型注册几个Java或者Python函数，模型根据用户的话决定调哪个、传什么参数。这个模式很直观，也确实能跑通不少demo。但一旦任务复杂起来，问题就暴露了：一个复杂任务往往要调很多次函数，每一次调用之间还有依赖关系，模型自己并不知道“先后顺序”和“中间结果怎么传递”。
Skills的核心变化在于：它把“单次调用”升级成“整段流程”。一个技能可以包含多个步骤，可以组合多个底层工具，可以内置状态管理，甚至可以定义失败重试和结果验证策略。模型不再需要靠提示词临时推断“现在该干什么”，而是直接匹配到一个成熟的工作流。
我举个具体对比。假设用户说“帮我把这篇文章的摘要提取出来，然后翻译成英文，再总结三个要点”。普通Function Calling的做法是：你注册了summarize、translate、extract_points三个函数，模型自己决定按什么顺序调，中途一旦上下文被压缩或者信息丢失，结果就很容易出问题。而Skills的做法是直接定义一个“内容处理工作流”技能，内置了每一步的输入输出约束和校验规则，模型只需要识别“这是一个内容处理任务”，然后整个过程自动流转。
1.2 技能不是插件，也不是工作流引擎
搞清楚Skills的定位很重要，否则很容易和另外两个概念混在一起。
第一，它和传统插件不一样。插件强调的是“扩展能力边界”，比如加一个PDF解析插件，那Agent就能读PDF了。但Skills强调的是“封装解决问题的能力”，PDF解析可能只是某个技能内部的其中一个步骤。Skills更侧重流程编排和智能调度，插件更侧重能力接入。
第二，它也不同于独立的工作流引擎。像Coze、Dify里那种编排好的工作流，通常是人先画好流程图，Agent严格按图执行。但Skills是有弹性的，它给出步骤框架，但每一步具体怎么执行、什么参数，仍然由模型自主决策。你可以理解为：工作流是“铁轨”，模型是“火车”，只能按轨道跑；而Skills是“任务手册 + 工具箱”，模型知道任务有几个阶段、每阶段用什么工具，但细节上保留灵活度。
第三，Skills的核心资产是“可复用的问题解决模式”。同一个技能，换一套底层API、换一个模型，依然能跑。因为技能层抽象的是方法论，不是具体实现。这也是我项目里坚持的原则：技能描述里不写死任何供应商API细节，只定义能力和验收标准。
2. 技能包的结构设计：四个模块缺一不可
2.1 技能描述：模型靠它做路由决策
技能描述是整个技能包的门面。模型接到用户请求后，第一件事就是判断“这个请求该匹配哪个技能”，判断依据就是技能描述。很多人在这一步偷懒，写一句“用于文本处理”就完了，结果模型什么都不匹配，或者全都匹配，表现非常不稳定。
我自己的做法是：描述必须包含三个部分。第一是“触发条件”，明确说明什么类型的请求应该选这个技能，最好给出正例和反例。第二是“执行目标”，让模型知道这个技能最终要交付什么。第三是“约束边界”，尤其是哪些情况不要用这个技能。
我踩过的一个典型坑是：把“处理用户日常请求”也写进描述里，结果这个技能变成了万能兜底，所有请求都往它身上怼，其他精细设计的技能反而没人用。后来我把描述改成“仅当用户明确请求翻译、改写、润色等文本编辑操作时启用”，效果马上就对了。
有个细节值得留意：现在主流模型对描述的理解能力都不差，但你依然要用“动词开头的祈使句”来写，比如“提取文章中的核心观点并生成结构化摘要”，而不是“该技能用于摘要生成”。前者的指令性更强，路由准确率明显更高。
2.2 参数契约：让模型知道每一步需要什么
技能内部多步执行时，参数传递是很容易翻车的地方。我曾见过一个技能包，第一步生成的内容写到临时变量，第二步却读不到，排查了半天发现是参数名大小写不一致。所以我在项目里定义了一套参数契约规范：
- 所有步骤间的传递参数必须显式声明，不允许“隐式变量”。
- 参数名统一采用驼峰命名，且必须有语义，禁止用a、b、tmp这种。
- 每个参数要标注类型和取值范围，模型调度时就知道该怎么填。
- 标记必选参数和可选参数，可选参数要提供默认值说明。
你可能觉得这有点小题大做，但实际跑起来就会发现，LLM生成的参数值有时候会“自创格式”。你定义了一个date类型，要求YYYY-MM-DD，它给你传“明天”。这种时候光靠口头约定没用，必须在参数契约层做格式约束，最好再加上一层校验函数兜底。
2.3 执行逻辑：把判断留给模型，把流程留给技能
我这里说的执行逻辑，不是指传统编程里那种严格的条件分支，而是一种“半结构化流程”。每个技能内部按阶段组织，比如“输入校验 → 内容分析 → 结果生成 → 结果验证”。模型在阶段内自由发挥，但阶段的推进顺序和完成标准由技能控制。
这个设计的好处是，即使模型在某个阶段输出质量不佳，技能框架依然能保证整体流程不会乱套。拿我的“技术文档翻译技能”举例，它内部定义了一个强制前置步骤：先把源文档术语表抽取出来，再开始翻译。因为如果直接翻译，同一个术语前后译法不一致，后期返工成本极高。有了这个流程约束，模型必须先做术语抽取，再进入翻译阶段。
另外，执行逻辑里要设计“出口条件”。每个阶段结束时，技能要能判断“这个阶段是否真的完成了”，而不是模型说一句“已完成”就放行。最简单的方式是校验产出物格式，更高级一点可以做语义相关性打分。
2.4 验证与回退：没有验证环节的技能包就是定时炸弹
技能包跑得多了，你会发现模型经常会“一本正经地胡说八道”。它可能完整执行了流程，但输出结果是错的。所以我每个技能都设计了一个内置验证器。
验证器分三种类型：格式验证、内容验证、逻辑验证。格式验证最简单，检查输出是否符合JSON结构或Markdown规范。内容验证常用关键词覆盖、实体匹配等手段，确认输出确实涵盖了输入的关键信息。逻辑验证则有点类似写单测，给技能塞几个已知答案的测试用例，跑一遍看输出是否合理。
如果验证没过，技能不要直接报错，而是进入回退流程。我常用的回退策略有两种：一是让模型基于验证结果做一轮修正，二是降低温度重新执行一次。这里有一个实际调参的心得：重试时的temperature可以适当降低，比如从0.7调到0.3，让模型更倾向保守正确的输出。
2.5 技能注册表：全局视角管理所有技能
当技能数量超过十个之后，你肯定会需要一个注册表。注册表记录每个技能的名称、版本、依赖工具、启用状态、平均调用延迟、成功率。这个表能帮你一眼看清哪个技能是“摆设”，哪个是“主力”。
更关键的是，注册表可以为模型提供“技能总览页”。我实测下来，让模型先看一份简短的所有技能清单，再去做路由决策，匹配准确率比让它凭空搜索技能库要高不少。清单不用详细描述每个技能，只列“技能名 + 一句话功能 + 适用场景关键词”，相当于给模型画了一幅地图。
3. 从0到1搭建一个实用的技能集
3.1 选定第一批技能：覆盖高频场景，但不过度设计
我建议第一次做技能集，不要贪多。选三到五个和你的业务最相关、调用频率最高的场景就够了。我在这个项目里选了四个：信息检索类、内容创作类、数据处理类、日程管理类。
选技能有个原则：“一个技能只解决一类问题，但这一类问题要覆盖足够多的变体”。比如内容创作技能，不只是“写文章”，而是覆盖“写提纲、写初稿、扩写、改写、总结”这一整族操作，因为它们在底层高度相似，合并成一个技能后，模型匹配的压力会小很多。
这里多说一句：很多人喜欢一个功能一个技能，最后技能列表长得像超市货架，看着很充实，实际用起来模型天天选择性困难。宁可少而精，把每个技能做厚做实。
3.2 以“信息检索技能”为例，看完整实现细节
信息检索是我所有技能里最底层的模块，其他技能经常要调它。所以这个技能的设计要求是：稳、快、结构化输出。下面是这个技能的完整定义：
技能名称: web_search_analyze 触发条件: - 用户请求包含["搜索", "查一下", "找资料", "最新消息"]等意图词 - 用户需要获取当前或近期的事实型信息 - 不适用于：用户只是闲聊、用户已有明确来源只需要翻译或摘要 执行阶段: 1. 查询词优化 - 输入: 原始用户问句 - 输出: 2~3个不同表述的搜索关键词组合 - 校验: 关键词必须包含核心实体词，禁止泛化词 2. 多源信息获取 - 调用搜索引擎API获取多个来源的网页摘要 - 至少获取5个独立来源，优先权威与时效性 3. 交叉验证 - 对比不同来源的信息差异性，标记矛盾点 - 对矛盾信息做置信度评分，无法确认的如实标注 4. 结构化输出 - 返回字段: 结论摘要 / 来源列表 / 置信度 / 信息缺口 - 输出格式: JSON 验证器: - 来源数量不少于3 - 每条结论必须有关联来源URL - 矛盾点必须如实呈现，禁止通过省略掩盖 回退策略: - 如第一阶段关键词校验未过，改为直接使用原始问句作为关键词 - 如搜索返回结果为空，尝试删除限定词并重试一次这个结构看起来简单，但我前前后后调整了四五个版本。最初版本里没有“交叉验证”阶段，结果就是模型搜到什么就说什么，完全不做可信度判断。后来我把“时效性”和“权威性”作为两个显式评分维度加进去，输出的可靠性才真正可用。
关于搜索实现，我用的是普通搜索引擎API，然后在技能层做了一次结果重排，把来源类型（新闻站点、百科、论坛、个人博客）和更新时间作为排序因子。这个重排逻辑其实很关键，因为原生搜索结果的时间排序经常不准，尤其是某些资讯聚合页。
3.3 内容创作技能的设计：程序化与创造性的平衡
内容创作技能的度最难把握。太自由了，模型容易放飞自我，输出一堆空话；太死板，又失去了“创作”的意义。我最后采用的方式是“框架约束 + 局部自由”。
具体来说，技能强制模型分三个阶段：先搭建结构大纲，再逐段扩写，最后整体润色。每个阶段之间设置检查点。写大纲阶段，技能要求输出“论点列表 + 每个论点的支撑素材占位”；扩写阶段则允许模型自由发挥文字风格；润色阶段只做句式和节奏调整，不做结构变更。
这里有一个我特别想分享的经验：如果你发现创作出来的内容总是“中规中矩但没灵魂”，问题往往出在技能描述里没有定义“风格锚点”。我在技能描述里加了一句“用具体案例和数据替代抽象描述，每段至少包含一个可验证的事实或示例”，输出质量立刻有了质的变化。
不要害怕给技能提要求，模型不会觉得你烦。它反而会在更明确的约束下给出更靠谱的结果。
3.4 技能间的协同：让一个技能调用另一个技能
当你有了多个技能之后，自然会遇到技能间协作的场景。比如“写一份行业报告”这个请求，既需要信息检索技能去搜资料，又需要内容创作技能来组织输出。
技能间调用有两种方式。一种是“串行编排”，在技能A的执行逻辑里显式指定“步骤三调用技能B”。另一种是“并行调度”，由Agent层的调度器同时调用多个技能，再把结果汇总。我实测下来，串行编排的稳定性更高，因为技能的上下文是连贯的，但速度较慢；并行调度快，可在汇总阶段容易出现信息冗余。
我现在的做法是：把“信息检索”设计成可被调用的公共技能，其他技能不重复实现搜索逻辑，而是在需要外部信息时调用它。这样既减少了技能间的功能重叠，也方便统一管理搜索质量和计费。
3.5 上下文的组织：保持技能内信息传递不失真
技能多步执行最怕的就是上下文丢失。模型在第一步读到的关键信息，到第三步可能就忘了，或者被截断了。这个问题在长任务场景下极其常见。
我的解决方案是三步走。第一，每个技能定义“上下文摘要点”，在指定步骤强制生成一份阶段性摘要，保留关键状态。第二，使用外置的记忆存储，把步骤间的关键产出写到结构化字段里，下一步从存储里取，而不是依赖模型自己的上下文。第三，对超过一定长度的内容做“预压缩”，不让原始文本直接进入模型上下文。
说起来好像不复杂，但真正做到位很费功夫。最核心的认知是：不要把模型上下文当成数据库，它只是“工作内存”，随时可能被清空。你要把必须保留的信息放到技能包自己的存储层里。
4. 技能包开发踩坑实录与排查方法
4.1 技能路由不准：模型总是选错技能
这是所有技能包开发者遇到的第一个高频问题。表现是：用户发了一个很明确的请求，但模型启用了一个完全不相关的技能，或者干脆不启用任何技能。
我的排查方法是从三个角度依次检查。先看技能描述是否写清楚了触发边界，特别是“什么情况下不要用这个技能”。再看技能数量是否过多，如果候选技能超过15个，模型的选择准确率会明显下降，建议做技能归类，把可以合并的先合并。最后看注册表里的技能清单是否被模型有效读取，有些框架下模型根本看不到完整清单，路由只能靠猜。
还有一个不太容易注意到的小坑：技能描述的关键词不要和技能内部的工具名重复。比如技能本身叫“search”，内部调用了一个工具函数也叫“search”，模型可能会混淆概念，导致路由决策异常。改名是成本最低的解决办法。
4.2 参数传递断裂：前一阶段的结果后一阶段读不到
这种问题通常表现为：第一步表单填写阶段正常，第二步数据分析阶段却报“字段不存在”。多数情况下不是数据真的丢了，而是技能框架里变量作用域定义不当。
排查技巧是把“阶段间传递的数据”显式打印出来，看实际传递的是什么东西。很多时候你会发现，模型在第一步输出的是自然语言文本，但第二步期望的是JSON，类型没法自动转换。我在项目里为此专门加了一个“类型适配器”，允许定义字段级别的类型转换规则：文本转JSON、时间文本转时间戳、逗号分隔字符串转数组。
记住，在Agent技能的开发里，显式永远比隐式可靠。任何跨步骤使用的数据，都应该在参数契约里提前声明，并且在代码里做好类型强校验。
4.3 技能输出质量不稳定：同一输入多次运行结果差异大
这个问题的根源通常是temperature参数设置不合理。内容创作技能需要一定的随机性，但信息检索和数据处理技能追求的是确定性。
我现在每个技能都配了独立的temperature档位：事实型任务用0.2以下，分析型任务用0.3到0.5，创作型任务用0.7左右。这个数值不是拍脑袋定的，而是针对每个技能做了一组对比实验，跑了几十个样本取了一个稳定性和质量平衡最好的点。
另外，如果你希望输出更稳定，可以在技能描述里加“输出原则”段落，比如“优先选择多数来源支持的观点”“不确定的内容明确标注”。这比单纯调温度更管用，因为模型在方法论层面就变得更保守、更可靠。
4.4 验证器误杀：好结果被判成坏结果
验证器太严或者太松都会出问题。太严会把合理输出都拦下来，太松则形同虚设。我调整验证器的经验是：先收集100条真实任务的输出结果，人工标记“合格/不合格”，然后用这批数据来定验证器的阈值。
比如格式验证，我曾在JSON校验里要求字段顺序完全一致，结果模型偶尔调换字段顺序就被误杀。后来改成“字段存在性 + 类型正确性”校验，误杀率大幅下降。内容验证同理，不要用“必须包含某词”这种硬规则，而是做语义相似度判断，低于阈值的再进入回退流程。
这里补充一个我常用的验证技巧：对同一个技能，跑三个不同的输入样本，把三个输出结果放在一起对比。如果三个输出高度一致，那大概率验证器是稳定的；如果输出五颜六色各有不同，多半是你约束给得太松了。
4.5 技能包的版本管理：改一个技能牵一发动全身
技能包也是代码，需要版本管理。但技能和普通代码有一个重要区别：技能的改动效果是非线性的，你以为只影响这个技能，实际上模型的路由策略会因此变化，进而影响其他技能的调用频率。
我现在使用一套“版本浮标”机制：技能包整体有一个版本号，每个技能又有自己的独立版本号。发布新版本前，跑一遍全量回归测试，看所有技能的指定样例是否通过，特别关注“原正常技能是否因新版技能发布而出现异常”。这部分看起来很琐碎，但确实能避免很多生产事故。
我个人强烈建议，每个技能包目录下都要放一个CHANGELOG文件，记录每次改动的动机、内容、影响范围。半年之后你会感谢这个习惯。
5. 技能包的验收评估与后续扩展思路
5.1 一套实用的技能包验收清单
做了这么多，最后说说怎么判断你的技能包到底合格没有。我总结了一张验收清单，每次新增或修改技能都按这个过一遍：
| 验收项 | 检查标准 | 不通过时的陷阱 |
|---|---|---|
| 路由准确率 | 100条真实请求，选对技能率≥90% | 描述边界不清，万能兜底技能出现 |
| 参数完整率 | 必填参数遗漏率≤5% | 参数契约声明不完整，缺默认值 |
| 执行完成率 | 技能流程跑通率≥90% | 阶段间数据传递断裂，验证器误杀 |
| 输出格式准确率 | 结构化输出可直接被程序消费率≥95% | 类型不匹配，字段名称漂移 |
| 结果质量人工评测 | 抽样30条，人工好评率≥80% | 温度太高，论述空泛 |
| 失败回退有效性 | 首次失败后回退成功率≥60% | 回退策略与主流程没有差异化 |
5.2 从技能集到技能市场：设计的复用价值
当技能包稳定之后，你会发现它的价值远远超出“一个功能模块”。因为技能封装的是方法论，它天然具备跨项目复用的能力。我现在的做法是，把常用的技能包做成独立仓库，不同项目通过依赖引入，遇到新问题先看有没有已有技能可以组合解决问题，而不是新写一个。
技能包的抽象粒度很关键。我自己的经验是：让技能尽量不依赖特定模型和特定API供应商。内部实现的差异通过配置项隔离，这样技能包才能在不同的Agent底座之间平滑迁移。这就像写业务代码时抽象出接口一样，在技能层也一样适用。
5.3 下一步可做的三个扩展方向
如果你已经跑通了一套技能包体系，后续值得投入的方向，我比较推荐这三个。第一个是“技能自进化”，基于用户反馈和自动评估结果，让技能包定期自我修正描述和流程；第二个是“多技能联合规划”，构建一个技能调度层，负责把复杂任务自动分解成多个技能的组合方案；第三个是“技能可观测性”，对每个技能的每次调用记录完整的输入、中间过程、输出和验证结果，方便定位和复盘。
这三个方向我都做了不同程度的尝试，最终的体会是：Agent Skills不是一个需要一次性做完美的宏大架构，而是一个允许你先跑起来、再持续迭代的工程实践。关键是先把流程跑通，把验证和回退做好，然后基于真实反馈一点点打磨。
这个项目做到现在，我最深刻的感受是：技能包的核心价值不在于把多少API封装起来，而在于把“怎么做一件事”的经验固化下来，让模型不用每次从头摸索。它像是给Agent配了一本操作手册，模型照着手册干活，效率和质量都会有质的提升。而且维护这本手册的过程，也是对自身业务理解不断加深的过程。如果你也在做Agent开发，我建议从一个小而精的技能包开始，跑通一条链路，你会有非常具体的收获。
