做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开发我建议从一个小而精的技能包开始跑通一条链路你会有非常具体的收获。