最近在忙着把手里的一个Agent项目从能跑通的演示推向能稳定交付的生产环境过程中发现一个很现实的问题模型再聪明如果每次干活都要临时写Prompt、临时调工具那Agent就只能停留在大型魔术表演现场的阶段。真正让它变成生产力工具的是一套结构化的技能库——也就是我今天想聊的主题agent-skills。所谓Skills通俗讲就是给Agent配一套可复用、可组合、可验证的执行模块。这篇文章不会跟你讲太多抽象概念而是结合我自己在真实项目里踩过的坑、试过的方案把Agent技能的设计思路、完整结构、实操流程和跨框架复用策略都摊开聊一遍。无论你是正在做Agent应用开发、还是准备把Agent接入业务流程这篇文章都应该能给你一套可以直接参考的落地方法。1. 为什么Agent需要的是技能体系而不是堆一堆工具1.1 单次对话的天花板模型有脑子但不一定有手很多人刚开始接触Agent的时候会有一个惯性认知既然大模型已经这么聪明了那我直接把需求说清楚它不就能把事情办了吗这个想法在纯聊天场景下是成立的但一旦涉及到真实业务动作——比如查询数据库、处理文件、调用外部接口、生成特定格式的报表——模型就尴尬了。它只能给你一段应该怎么做的文本却不能真正触发任何外部动作。早期大家用函数调用机制来解决这个问题你定义一堆工具函数告诉模型这些函数的存在和参数格式模型在对话过程中帮你做函数调用规划。但这里有个隐藏痛点函数调用的描述是零散的每个函数都是孤岛。你告诉模型有一个函数能读取Excel有一个函数能发送邮件模型确实能用但它怎么组合这些函数每一步之间的业务规则由谁来约束同一个业务场景换个项目又要重新描述一遍。说白了函数调用是手但没有操作规程。技能这个概念弥补的正是这一层。1.2 Skills的本质把做事的方法封装成可复用的资产我习惯用岗位说明书操作手册来类比给团队里人解释一个函数等于你能调用这台打印机一个技能等于打印一份带封面和页码的季度报告这件完整的事——它包含了调哪个函数、按什么顺序、什么格式输入、出错了怎么兜底。所以技能的日常定义是一段完整的任务描述 一整套执行逻辑步骤清单 必要的参数契约 验证方式打包成为一个可独立加载、可独立升级的模块。它解决的不仅是怎么调工具更是这个任务应该这么办的方法论。1.3 三个直接受益点效率、稳定、可维护先说效率。技能库沉淀之后同一个类别的任务不需要再从头定义。比如我做过一个数据清洗技能最初为某个项目写的后来换了个项目数据源从数据库变成了API返回的JSON只需要改一下数据接入层清理逻辑完全复用。这是效率上的收益。再说稳定。模型的输出天然有随机性但业务流程里有些东西不能随机。技能把关键规则固化下来之后Agent的行为方差会明显降低。用我同事的话说以前它像是一个发挥不稳定的实习生定义了技能以后它至少像一个理解了操作流程但偶尔手误的实习生。最后是维护。业务规则变了我只需要改对应的技能模块而不是全局重调Prompt。技能之间相互隔离改了一个出问题不会整体翻车。2. 拆解一个Skill的完整结构元数据、描述、执行逻辑、验证2.1 元数据层让Agent知道这个技能存在技能库一旦超过10个Agent在面对用户需求、决定要不要调用某个技能的时候靠的不是把所有技能内容都塞进上下文而是先扫描技能的元数据。元数据通常会包含技能ID、版本号、权限等级、适用标签、触发场景关键词。举个例子我设计了一个周报自动汇总技能它的元数据里会写上标签周报、汇总、markdown、团队管理这样当对话里出现帮我看看这周大家的周报时Agent能快速把注意力定位到该技能上。这里有一个特别容易忽略的点元数据里的标签不是给程序做精确匹配用的而是给模型做模糊唤回用的。所以写标签的时候我会刻意加入一些口语化的业务词汇比如划水进度产出这类平时同事说话会提到的词。实测下来这种贴近业务口语的标签比严格的技术术语命中率更高。2.2 描述层给Agent的自我介绍说明书描述层是技能的最关键一环它决定了模型能否在正确的时间点调用这个技能。很多人在写描述的时候犯的毛病是写成给产品看的功能说明而不是给模型看的调用导引。一个合格的技能描述应当包含三部分这个技能完成什么任务、在什么输入条件下应该被触发、调用后大概会产生什么输出。最典型的反面例子是某技能描述写本模块用于对多维数据进行深度整合分析并产出可视化结论看着很有气势但模型看完根本不知道该什么时候用。换成当用户要求把多份Excel或CSV数据合并为一份汇总报表时使用本技能就清晰多了。另外我会在描述里加不做什么的负面约束。比如周报汇总技能里我会写仅负责文本汇总不做绩效评分不负责发邮件。负面约束能有效避免模型在触发技能后自作主张地越权操作。这一点在后面的踩坑章节还会专门展开。2.3 执行逻辑层技能的核心内容执行逻辑是技能真正干活的部分形式上可以是自然语言的步骤清单也可以是代码脚本或者是两者的混合。我个人的最佳实践是步骤清单为主关键环节用代码实现。一个通用技能的步骤组织方式大致是——先做输入数据校验再做业务处理然后做输出格式化。以周报汇总为例执行逻辑会包含读取所有周报文件、按成员姓名和时间字段去重、剔除空文档、提取本周完成和下周计划两个板块、按模板合并、输出为Markdown。每一步之间要给出清晰的转换规则避免模型自由发挥。执行逻辑的编写方式还有一个讲究要写成可顺序执行的操作指令而不是目标描述。说整理所有人的周报没有操作价值说遍历指定目录下所有文件名包含reports的文件按创建时间升序读取并提取正文标题才是能被执行的指令。我在多步执行逻辑里还会刻意加入每完成一步输出一个中间标记变量的设计。比如每一步完成之后让模型在内部状态里更新一个JSON字段如 step1_done: true这样技能能在中途掌握自己执行到哪了出问题也好定位。2.4 验证层让技能可被信任验证层是技能和普通Prompt之间最大的区别。一个Prompt只需要生成一段话但一个技能必须保证任务被正确完成。我在周报汇总技能里加了三道验证第一道确认输入文件格式合法第二道确认合并后的输出中每个成员只出现一次若发现重复记录自动保留时间戳最新的一条第三道确认最终输出的Markdown符合模板的标题层级结构如果缺失大标题则自动补全。任何一道验证失败技能都会回到出错的位置做修正而不是直接返回半成品。当初没有加验证层的时候这个技能出现过好几次输出看起来挺完整、实际漏了两个人的情况。加了验证层之后这种低级错误基本绝迹了。验证逻辑本身不用写得多复杂关键是要存在。3. 高质量技能设计的四条军规命名、边界、参数与版本3.1 一个技能只干一件事边界要写进描述里技能设计的第一个大坑就是大而全。团队里常有伙伴把数据导入与清洗与建模与可视化做成一个技能理由是这些都是数据处理流程的一部分。结果模型一旦触发它经常在内部逻辑里自我迷失不是这里多了一步就是那里跳过了一步。我的拆解标准很简单如果一个技能的执行逻辑超过15个步骤或者产出物包含多种不同类型的文件、面向多个不同目的就应该拆分。拿数据处理举例我会拆成数据导入数据清洗特征衍生报表生成四个技能每个技能完成一个可以被验证的原子任务。技能拆细了之后还有一个额外好处模型可以根据用户需求灵活编排技能组合。边界除了干事的范围还包括不干事的范围。我在描述里专门会写一段约束条款比如本技能不做格式转换、本技能不负责数据删改等目的就是让技能边界可预期。3.2 参数设计要少而准参数是技能与外部世界的接口。设计参数的时候最忌讳的一是贪多二是含义模糊。参数一多模型在调用时很容易纠结于这个参数到底要不要传、传什么值推理时间变长还容易出错。我自己常用的做法是最多不超过6个参数必须明确区分必填和可选。必填参数要少一般保持在3个以内可选参数则需要有明确兜底值。比如周报汇总技能的必填参数只有两个周报目录路径、汇总模板类型可选参数是时间范围默认值为本周一至周日。参数命名也要生活化。不要在参数名里用source_data_entity_list这种让人犯晕的名字直接用周报文件列表这种自然语言化的名称模型在调用时认知负担会小很多。实测下来命名越接近自然语言Agent漏传参数的概率越低。3.3 写给靠谱实习生的执行逻辑这是我在技能设计上最重要的一条心得执行逻辑不是写给模型看的最终目标而是写给一个第一次接手这个任务的靠谱实习生看的操作指南。请一个实习生去汇总周报你不会只跟他说把周报汇总好你会告诉他先建一个以本周日期命名的文件夹把每个人发的文件放进去先打开读一遍看看有没有空文档去掉那些只有标题没有内容的文件然后按固定顺序合并最后检查一下的人数对不对。技能的执行逻辑就应该是这样的颗粒度。为了让执行逻辑更可靠我推荐在描述步骤的时候用动词开头的祈使句短句这样模型在执行的时候可以逐步跟着动作走。每步之间要有明确的数据流转关系比如读取结果存入变量input_docs下一步基于input_docs做去重。这种写法跑出来的技能稳定性明显更高。3.4 版本管理技能的迭代不等于推翻技能不是一次性写完就完事的业务规则一定会变化。我在项目里一开始没有对技能做版本管理结果有一次改了数据清洗规则导致之前的所有报表口径全部变了。从那之后我引入了语义化版本号规则大版本号变化代表行为逻辑的重大改变小版本号代表修复或优化Patch版本代表细微的文案调整。不同版本之间不一定要互相兼容。我在技能目录里保留了一个previous_versions文件夹当新版本技能上线后出现问题时可以一键切回旧版本。配合接口层的开关设计能在不改代码的情况下按需回滚。对于生产环境的Agent应用这项设计几乎是必须的否则技能出错时你只能干瞪眼。4. 实战从零搭建周报自动汇总技能的全流程4.1 需求分析从模糊需求到可执行模块先看一个真实的任务需求帮我把大家的周报汇总成一份。听起来一句话但落到技能设计上必须拆出子任务链。这个需求实际包含五个环节读取从指定目录读全部周报文档、筛选剔除空文档和测试文档、清洗处理格式不一致、去掉重复提交、合并按模板拼装成一份Markdown、输出生成汇总文件并返回路径。这五步中任何一步没定义清楚结果的质量就有随机性。拆完之后还需要和业务方确认一个关键规则如果有人本周没有提交周报汇总里是留空位还是直接忽略这种细节不确认技能跑得再顺也不符合业务预期。我的选择是记录缺失名单并放在汇总文件的附录里这样既不破坏汇总的连贯性又能提醒团队的跟进。4.2 技能的Schema设计实例下面是我在这个项目里实际用的技能定义简化结构在JSON Schema风格的组织下技能的自包含性会非常清晰{ skill_id: weekly_report_aggregator, version: 2.1.0, name: 周报自动汇总, tags: [周报, 汇总, markdown, 团队管理], description: 当用户要求把多份周报文档合并成一份汇总报告时使用。仅处理文本汇总不做绩效评价不负责发送邮件。, parameters: [ { name: 周报目录路径, type: string, required: true, description: 存放周报文件的文件夹路径支持相对路径 }, { name: 时间范围, type: string, required: false, description: 周报对应的时间周期默认本周一至周日 } ], steps: [ 1. 读取周报目录路径下所有文件筛选出文件名包含reports或周报字样的文档, 2. 逐份读取文档剔除空文档和仅含无效占位符的文档结果存入变量valid_docs, 3. 基于成员姓名和时间字段对valid_docs去重保留时间戳最新的版本, 4. 解析每份文档提取本周完成与下周计划两个板块的内容, 5. 按汇总模板合并所有内容生成Markdown文件保存到当前目录/reports_merged/, 6. 检查输出文件中的成员数量与valid_docs去重后的数量一致若不一致则报错并列出缺失名单 ], validation: [ 输出文件必须存在且非空, 输出文件中的成员数必须等于去重后的文档数, 输出文件必须包含固定的大标题与分节标题 ] }这套结构我每次在新建技能的时候都会先搭好然后再往里填充业务逻辑。好处是无论技能做什么它的壳完整了后面换场景只需要改中间steps的内容。4.3 联调与验证的完整过程写成定义只是第一步真正让它正常工作还要经过三轮测试。第一轮用全正常的输入我准备了5份格式统一、内容完整的周报看能否按照模板合并。结果顺利通过但这个顺利反而提醒了我——用例太完美了覆盖不到现实。于是第二轮开始加入脏数据一个空文档、一份重复提交的文档、一份标题格式缺失的文档。这一轮果然出了状况空文档没有被剔除它在后续合并时造成了一个空章节其他内容全部被挤到了错误的标题层级下。原因是我只筛选了文件后缀没有检查文档正文长度修正逻辑后加上了正文少于20字判定为无效文档的规则。第三轮则是边界测试传入一个空目录。这时候技能应该明确返回错误提示而不是生成一份空报告。这一步也暴露了问题技能在没有输入的情况下进入了死循环式的自查花了好几次重试才跳出流程。后来在步骤里第一个动作加上了前置校验若目录下无有效文档直接返回提示并要求用户检查路径。这三轮测试跑完这个技能才算真正达到可上线的状态。脚本测试大概只花了两小时但后面省下来的调试时间是以天为单位的。4.4 接入Agent前后的效果对比接入技能之前我让模型直接汇总周报表现非常不稳定有时它在步骤中断掉有时它自作主张给周报内容起了新标题还有一次它把暂无进展的成员直接跳过没写导致汇总缺少关键成员信息。最头疼的是每次调整Prompt效果只能变好一阵过几天换个输入格式又出幺蛾子。接入技能库之后同样的任务只需要一句话触发把上周周报汇总一下。模型自动匹配到该技能、按预设逻辑执行、输出固定模板文件。连续两周跑了30多份周报产出的一致性明显提升。最直观的体验是后续再有人提需求我不需要再陪同调Prompt了非技术背景的同事也能自己触发技能完成任务。5. 跨框架复用声明式与命令式两种路线的迁移策略5.1 两种主流实现路线的差异在Agent技能这件事上目前市面上主要有两种实现路线。第一种是我称之为声明式的路线代表做法是把技能定义成文件如前面写的JSON结构技能内容和代码分离便于管理和分享。插件化程度高改动技能不涉及代码发布流程适合业务人员参与维护。第二种是命令式的路线代表做法是把技能封装成代码模块函数加装饰器通过运行时注册机制挂载到Agent上。它的好处是逻辑表达能力更强适合复杂计算和系统调用缺点是对开发能力有要求而且技能与框架耦合较紧。这两种路线之间并没有绝对的优劣实际取什么路线取决于团队和场景。我这里想重点聊的是无论用哪种路线技能内在的步骤逻辑和框架绑定的挂载方式都应该被解耦这是跨框架复用的基础。5.2 迁移策略把技能逻辑与环境绑定分离我真实的项目里出现过这样的经历先在一个实验性的Agent框架里写好了数据清洗技能后来生产环境换了另一个框架技能差点全部作废。重新排查的时候发现框架差异只影响技能如何被发现和执行器如何被调用而不影响清洗逻辑本身。于是我把项目结构改成了三层分离第一层是技能目录JSON定义第二层是描述文件模型可见的说明第三层是执行器真正运行步骤逻辑的代码。框架适配层只负责把执行器包装成对应框架能识别的格式技能核心逻辑完全不变。拿一个网页内容摘要技能举例在声明式框架里它通过技能文件描述加Python执行脚本来跑在命令式框架里它被包装成一个有函数注解的调用入口。两者的核心逻辑是同一段代码不同的只是最外面的那层壳。5.3 一个技能适配两套框架的实操参考具体做法是写一个统一的执行器接口对外暴露一个入参、出参协议。任何技能只要实现了这个协议框架适配层就能把它注册成对应的工具入口或技能文件。以联网搜索摘要技能为例它的执行器接收一个搜索关键词参数内部完成搜索、去重、摘要生成三步最终返回一段带来源链接的摘要文本。在声明式框架下我需要写一份格式描述文件注明参数名称、类型和触发场景再把执行器路径指向函数。在命令式框架下则只需要导入执行器函数挂上注解和权限标记。迁移过程中最常见的坑是返回格式不兼容。有的框架要求Agent工具必须返回字符串有的框架要求必须是结构化字典对象。这种差异应该由适配层负责转换而不是去改技能内部逻辑。把这点想通以后再往第三套框架迁移的时候新增工作量就只剩下一个适配器了。6. 三个真实踩坑记录描述抽象、过度复用与上下文污染6.1 描述写得太像人话Agent反而不认识这是我早期技能库上线时最常出现的问题。当时我觉得技能描述应该写得像产品文案要优雅、完整、有说服力。结果有一次Agent面对一个明显应该触发表格透视技能的需求居然完全绕过了技能自己凭空生成了一套不存在的透视结果。排查了很久才发现原因就是技能描述里写的是对数据进行多维度洞察并生成透视表格模型压根没把这句漂亮话和实际操作的数据透视表对应起来。后来我换成了极其朴素的写法当用户要求对二维表格做按行、按列汇总计算时使用本技能。描述里的每一个词都有对应的可检测行为。从那之后这个技能的匹配率大幅提升。技能描述不是传播文案它是给模型做意图识别的路标越直白越好。6.2 过度复用导致的责任不清技能库建设到后期团队里开始流行复用一切的倾向。有人觉得既然发送邮件在很多流程里都用到那就直接在技能库里做一个通用的通信与通知技能把所有消息发送能力都塞里面。结果这个技能上线后问题不断用户只是要发一封简单邮件模型却触发了复杂的通信与通知流程附带了一堆无关检查。更糟糕的是后续在消息通知场景里想改样式却发现改这个技能会同时影响邮件流程和站内信流程牵一发而动全身。最后我把这个通用技能拆成了发送邮件、发送站内通知、生成通知摘要三个独立技能各自维护各自的模板和规则。拆完之后复用反而变高效了——因为每个技能都变成了最小单元组合成本远低于整体修改的成本。6.3 上下文污染技能内部输出主对话最后这个坑比较隐蔽但杀伤力很大。有一次我给某个技能加了过程可视化的功能让它在执行过程中输出日志本来是为了方便调试结果这些日志没有做隔离直接暴露在了主对话上下文里。模型在下一次回复时被日志中的中间数据带偏了。比如它看到日志里有一条清洗后剩余132条记录在下一次用户问题里就自作聪明地引用这个数字实际与当前问题毫无关系。这就是典型的上下文污染问题——技能内部的中间计算信息不应该让外部看到。找到原因后我的解决方案是设定清晰的内部状态与对外返回分离规则技能执行的中间变量全部放在内部上下文窗口只有最终结果和必要的完成标记对外可见。如果确实需要让Agent知道自己执行过什么也只返回一个小型摘要对象包含步骤列表和结果路径不含中间计算细节。这个坑也让我养成了一个习惯任何技能的调试日志都要有一个debug开关且默认关闭。在排查问题时临时打开排查完必须复位避免日志内容长期混入正常的会话记录里。回到开头那句话Agent能不能成为生产力工具很大程度上取决于它有没有一只靠谱的手而agent-skills就是这只看手的骨架和肌肉。我越是深入做技能库越觉得做这件事的最大门槛不是写代码而是把你日常做事的方法彻彻底底想清楚——边界是什么、步骤是什么、怎么算成功、出错怎么办。把这些想明白了写技能就是顺水推舟的事想不明白再多的框架和工具也救不了。最后再分享一个小技巧技能库上线之后定期回头审视一下哪些技能被高频触发、哪些技能一次都没被用到。前者说明你做对了后者说明它可能和真实需求脱节了——该改描述改描述该砍掉就砍掉技能库和任何产品一样需要做减法而不是一味堆功能。 
长河君 · 2026/10/13 23:43:58 · 阅读 1.2k Agent技能库设计实战：从函数调用到可复用技能体系
最近在忙着把手里的一个Agent项目从能跑通的演示推向能稳定交付的生产环境过程中发现一个很现实的问题模型再聪明如果每次干活都要临时写Prompt、临时调工具那Agent就只能停留在大型魔术表演现场的阶段。真正让它变成生产力工具的是一套结构化的技能库——也就是我今天想聊的主题agent-skills。所谓Skills通俗讲就是给Agent配一套可复用、可组合、可验证的执行模块。这篇文章不会跟你讲太多抽象概念而是结合我自己在真实项目里踩过的坑、试过的方案把Agent技能的设计思路、完整结构、实操流程和跨框架复用策略都摊开聊一遍。无论你是正在做Agent应用开发、还是准备把Agent接入业务流程这篇文章都应该能给你一套可以直接参考的落地方法。1. 为什么Agent需要的是技能体系而不是堆一堆工具1.1 单次对话的天花板模型有脑子但不一定有手很多人刚开始接触Agent的时候会有一个惯性认知既然大模型已经这么聪明了那我直接把需求说清楚它不就能把事情办了吗这个想法在纯聊天场景下是成立的但一旦涉及到真实业务动作——比如查询数据库、处理文件、调用外部接口、生成特定格式的报表——模型就尴尬了。它只能给你一段应该怎么做的文本却不能真正触发任何外部动作。早期大家用函数调用机制来解决这个问题你定义一堆工具函数告诉模型这些函数的存在和参数格式模型在对话过程中帮你做函数调用规划。但这里有个隐藏痛点函数调用的描述是零散的每个函数都是孤岛。你告诉模型有一个函数能读取Excel有一个函数能发送邮件模型确实能用但它怎么组合这些函数每一步之间的业务规则由谁来约束同一个业务场景换个项目又要重新描述一遍。说白了函数调用是手但没有操作规程。技能这个概念弥补的正是这一层。1.2 Skills的本质把做事的方法封装成可复用的资产我习惯用岗位说明书操作手册来类比给团队里人解释一个函数等于你能调用这台打印机一个技能等于打印一份带封面和页码的季度报告这件完整的事——它包含了调哪个函数、按什么顺序、什么格式输入、出错了怎么兜底。所以技能的日常定义是一段完整的任务描述 一整套执行逻辑步骤清单 必要的参数契约 验证方式打包成为一个可独立加载、可独立升级的模块。它解决的不仅是怎么调工具更是这个任务应该这么办的方法论。1.3 三个直接受益点效率、稳定、可维护先说效率。技能库沉淀之后同一个类别的任务不需要再从头定义。比如我做过一个数据清洗技能最初为某个项目写的后来换了个项目数据源从数据库变成了API返回的JSON只需要改一下数据接入层清理逻辑完全复用。这是效率上的收益。再说稳定。模型的输出天然有随机性但业务流程里有些东西不能随机。技能把关键规则固化下来之后Agent的行为方差会明显降低。用我同事的话说以前它像是一个发挥不稳定的实习生定义了技能以后它至少像一个理解了操作流程但偶尔手误的实习生。最后是维护。业务规则变了我只需要改对应的技能模块而不是全局重调Prompt。技能之间相互隔离改了一个出问题不会整体翻车。2. 拆解一个Skill的完整结构元数据、描述、执行逻辑、验证2.1 元数据层让Agent知道这个技能存在技能库一旦超过10个Agent在面对用户需求、决定要不要调用某个技能的时候靠的不是把所有技能内容都塞进上下文而是先扫描技能的元数据。元数据通常会包含技能ID、版本号、权限等级、适用标签、触发场景关键词。举个例子我设计了一个周报自动汇总技能它的元数据里会写上标签周报、汇总、markdown、团队管理这样当对话里出现帮我看看这周大家的周报时Agent能快速把注意力定位到该技能上。这里有一个特别容易忽略的点元数据里的标签不是给程序做精确匹配用的而是给模型做模糊唤回用的。所以写标签的时候我会刻意加入一些口语化的业务词汇比如划水进度产出这类平时同事说话会提到的词。实测下来这种贴近业务口语的标签比严格的技术术语命中率更高。2.2 描述层给Agent的自我介绍说明书描述层是技能的最关键一环它决定了模型能否在正确的时间点调用这个技能。很多人在写描述的时候犯的毛病是写成给产品看的功能说明而不是给模型看的调用导引。一个合格的技能描述应当包含三部分这个技能完成什么任务、在什么输入条件下应该被触发、调用后大概会产生什么输出。最典型的反面例子是某技能描述写本模块用于对多维数据进行深度整合分析并产出可视化结论看着很有气势但模型看完根本不知道该什么时候用。换成当用户要求把多份Excel或CSV数据合并为一份汇总报表时使用本技能就清晰多了。另外我会在描述里加不做什么的负面约束。比如周报汇总技能里我会写仅负责文本汇总不做绩效评分不负责发邮件。负面约束能有效避免模型在触发技能后自作主张地越权操作。这一点在后面的踩坑章节还会专门展开。2.3 执行逻辑层技能的核心内容执行逻辑是技能真正干活的部分形式上可以是自然语言的步骤清单也可以是代码脚本或者是两者的混合。我个人的最佳实践是步骤清单为主关键环节用代码实现。一个通用技能的步骤组织方式大致是——先做输入数据校验再做业务处理然后做输出格式化。以周报汇总为例执行逻辑会包含读取所有周报文件、按成员姓名和时间字段去重、剔除空文档、提取本周完成和下周计划两个板块、按模板合并、输出为Markdown。每一步之间要给出清晰的转换规则避免模型自由发挥。执行逻辑的编写方式还有一个讲究要写成可顺序执行的操作指令而不是目标描述。说整理所有人的周报没有操作价值说遍历指定目录下所有文件名包含reports的文件按创建时间升序读取并提取正文标题才是能被执行的指令。我在多步执行逻辑里还会刻意加入每完成一步输出一个中间标记变量的设计。比如每一步完成之后让模型在内部状态里更新一个JSON字段如 step1_done: true这样技能能在中途掌握自己执行到哪了出问题也好定位。2.4 验证层让技能可被信任验证层是技能和普通Prompt之间最大的区别。一个Prompt只需要生成一段话但一个技能必须保证任务被正确完成。我在周报汇总技能里加了三道验证第一道确认输入文件格式合法第二道确认合并后的输出中每个成员只出现一次若发现重复记录自动保留时间戳最新的一条第三道确认最终输出的Markdown符合模板的标题层级结构如果缺失大标题则自动补全。任何一道验证失败技能都会回到出错的位置做修正而不是直接返回半成品。当初没有加验证层的时候这个技能出现过好几次输出看起来挺完整、实际漏了两个人的情况。加了验证层之后这种低级错误基本绝迹了。验证逻辑本身不用写得多复杂关键是要存在。3. 高质量技能设计的四条军规命名、边界、参数与版本3.1 一个技能只干一件事边界要写进描述里技能设计的第一个大坑就是大而全。团队里常有伙伴把数据导入与清洗与建模与可视化做成一个技能理由是这些都是数据处理流程的一部分。结果模型一旦触发它经常在内部逻辑里自我迷失不是这里多了一步就是那里跳过了一步。我的拆解标准很简单如果一个技能的执行逻辑超过15个步骤或者产出物包含多种不同类型的文件、面向多个不同目的就应该拆分。拿数据处理举例我会拆成数据导入数据清洗特征衍生报表生成四个技能每个技能完成一个可以被验证的原子任务。技能拆细了之后还有一个额外好处模型可以根据用户需求灵活编排技能组合。边界除了干事的范围还包括不干事的范围。我在描述里专门会写一段约束条款比如本技能不做格式转换、本技能不负责数据删改等目的就是让技能边界可预期。3.2 参数设计要少而准参数是技能与外部世界的接口。设计参数的时候最忌讳的一是贪多二是含义模糊。参数一多模型在调用时很容易纠结于这个参数到底要不要传、传什么值推理时间变长还容易出错。我自己常用的做法是最多不超过6个参数必须明确区分必填和可选。必填参数要少一般保持在3个以内可选参数则需要有明确兜底值。比如周报汇总技能的必填参数只有两个周报目录路径、汇总模板类型可选参数是时间范围默认值为本周一至周日。参数命名也要生活化。不要在参数名里用source_data_entity_list这种让人犯晕的名字直接用周报文件列表这种自然语言化的名称模型在调用时认知负担会小很多。实测下来命名越接近自然语言Agent漏传参数的概率越低。3.3 写给靠谱实习生的执行逻辑这是我在技能设计上最重要的一条心得执行逻辑不是写给模型看的最终目标而是写给一个第一次接手这个任务的靠谱实习生看的操作指南。请一个实习生去汇总周报你不会只跟他说把周报汇总好你会告诉他先建一个以本周日期命名的文件夹把每个人发的文件放进去先打开读一遍看看有没有空文档去掉那些只有标题没有内容的文件然后按固定顺序合并最后检查一下的人数对不对。技能的执行逻辑就应该是这样的颗粒度。为了让执行逻辑更可靠我推荐在描述步骤的时候用动词开头的祈使句短句这样模型在执行的时候可以逐步跟着动作走。每步之间要有明确的数据流转关系比如读取结果存入变量input_docs下一步基于input_docs做去重。这种写法跑出来的技能稳定性明显更高。3.4 版本管理技能的迭代不等于推翻技能不是一次性写完就完事的业务规则一定会变化。我在项目里一开始没有对技能做版本管理结果有一次改了数据清洗规则导致之前的所有报表口径全部变了。从那之后我引入了语义化版本号规则大版本号变化代表行为逻辑的重大改变小版本号代表修复或优化Patch版本代表细微的文案调整。不同版本之间不一定要互相兼容。我在技能目录里保留了一个previous_versions文件夹当新版本技能上线后出现问题时可以一键切回旧版本。配合接口层的开关设计能在不改代码的情况下按需回滚。对于生产环境的Agent应用这项设计几乎是必须的否则技能出错时你只能干瞪眼。4. 实战从零搭建周报自动汇总技能的全流程4.1 需求分析从模糊需求到可执行模块先看一个真实的任务需求帮我把大家的周报汇总成一份。听起来一句话但落到技能设计上必须拆出子任务链。这个需求实际包含五个环节读取从指定目录读全部周报文档、筛选剔除空文档和测试文档、清洗处理格式不一致、去掉重复提交、合并按模板拼装成一份Markdown、输出生成汇总文件并返回路径。这五步中任何一步没定义清楚结果的质量就有随机性。拆完之后还需要和业务方确认一个关键规则如果有人本周没有提交周报汇总里是留空位还是直接忽略这种细节不确认技能跑得再顺也不符合业务预期。我的选择是记录缺失名单并放在汇总文件的附录里这样既不破坏汇总的连贯性又能提醒团队的跟进。4.2 技能的Schema设计实例下面是我在这个项目里实际用的技能定义简化结构在JSON Schema风格的组织下技能的自包含性会非常清晰{ skill_id: weekly_report_aggregator, version: 2.1.0, name: 周报自动汇总, tags: [周报, 汇总, markdown, 团队管理], description: 当用户要求把多份周报文档合并成一份汇总报告时使用。仅处理文本汇总不做绩效评价不负责发送邮件。, parameters: [ { name: 周报目录路径, type: string, required: true, description: 存放周报文件的文件夹路径支持相对路径 }, { name: 时间范围, type: string, required: false, description: 周报对应的时间周期默认本周一至周日 } ], steps: [ 1. 读取周报目录路径下所有文件筛选出文件名包含reports或周报字样的文档, 2. 逐份读取文档剔除空文档和仅含无效占位符的文档结果存入变量valid_docs, 3. 基于成员姓名和时间字段对valid_docs去重保留时间戳最新的版本, 4. 解析每份文档提取本周完成与下周计划两个板块的内容, 5. 按汇总模板合并所有内容生成Markdown文件保存到当前目录/reports_merged/, 6. 检查输出文件中的成员数量与valid_docs去重后的数量一致若不一致则报错并列出缺失名单 ], validation: [ 输出文件必须存在且非空, 输出文件中的成员数必须等于去重后的文档数, 输出文件必须包含固定的大标题与分节标题 ] }这套结构我每次在新建技能的时候都会先搭好然后再往里填充业务逻辑。好处是无论技能做什么它的壳完整了后面换场景只需要改中间steps的内容。4.3 联调与验证的完整过程写成定义只是第一步真正让它正常工作还要经过三轮测试。第一轮用全正常的输入我准备了5份格式统一、内容完整的周报看能否按照模板合并。结果顺利通过但这个顺利反而提醒了我——用例太完美了覆盖不到现实。于是第二轮开始加入脏数据一个空文档、一份重复提交的文档、一份标题格式缺失的文档。这一轮果然出了状况空文档没有被剔除它在后续合并时造成了一个空章节其他内容全部被挤到了错误的标题层级下。原因是我只筛选了文件后缀没有检查文档正文长度修正逻辑后加上了正文少于20字判定为无效文档的规则。第三轮则是边界测试传入一个空目录。这时候技能应该明确返回错误提示而不是生成一份空报告。这一步也暴露了问题技能在没有输入的情况下进入了死循环式的自查花了好几次重试才跳出流程。后来在步骤里第一个动作加上了前置校验若目录下无有效文档直接返回提示并要求用户检查路径。这三轮测试跑完这个技能才算真正达到可上线的状态。脚本测试大概只花了两小时但后面省下来的调试时间是以天为单位的。4.4 接入Agent前后的效果对比接入技能之前我让模型直接汇总周报表现非常不稳定有时它在步骤中断掉有时它自作主张给周报内容起了新标题还有一次它把暂无进展的成员直接跳过没写导致汇总缺少关键成员信息。最头疼的是每次调整Prompt效果只能变好一阵过几天换个输入格式又出幺蛾子。接入技能库之后同样的任务只需要一句话触发把上周周报汇总一下。模型自动匹配到该技能、按预设逻辑执行、输出固定模板文件。连续两周跑了30多份周报产出的一致性明显提升。最直观的体验是后续再有人提需求我不需要再陪同调Prompt了非技术背景的同事也能自己触发技能完成任务。5. 跨框架复用声明式与命令式两种路线的迁移策略5.1 两种主流实现路线的差异在Agent技能这件事上目前市面上主要有两种实现路线。第一种是我称之为声明式的路线代表做法是把技能定义成文件如前面写的JSON结构技能内容和代码分离便于管理和分享。插件化程度高改动技能不涉及代码发布流程适合业务人员参与维护。第二种是命令式的路线代表做法是把技能封装成代码模块函数加装饰器通过运行时注册机制挂载到Agent上。它的好处是逻辑表达能力更强适合复杂计算和系统调用缺点是对开发能力有要求而且技能与框架耦合较紧。这两种路线之间并没有绝对的优劣实际取什么路线取决于团队和场景。我这里想重点聊的是无论用哪种路线技能内在的步骤逻辑和框架绑定的挂载方式都应该被解耦这是跨框架复用的基础。5.2 迁移策略把技能逻辑与环境绑定分离我真实的项目里出现过这样的经历先在一个实验性的Agent框架里写好了数据清洗技能后来生产环境换了另一个框架技能差点全部作废。重新排查的时候发现框架差异只影响技能如何被发现和执行器如何被调用而不影响清洗逻辑本身。于是我把项目结构改成了三层分离第一层是技能目录JSON定义第二层是描述文件模型可见的说明第三层是执行器真正运行步骤逻辑的代码。框架适配层只负责把执行器包装成对应框架能识别的格式技能核心逻辑完全不变。拿一个网页内容摘要技能举例在声明式框架里它通过技能文件描述加Python执行脚本来跑在命令式框架里它被包装成一个有函数注解的调用入口。两者的核心逻辑是同一段代码不同的只是最外面的那层壳。5.3 一个技能适配两套框架的实操参考具体做法是写一个统一的执行器接口对外暴露一个入参、出参协议。任何技能只要实现了这个协议框架适配层就能把它注册成对应的工具入口或技能文件。以联网搜索摘要技能为例它的执行器接收一个搜索关键词参数内部完成搜索、去重、摘要生成三步最终返回一段带来源链接的摘要文本。在声明式框架下我需要写一份格式描述文件注明参数名称、类型和触发场景再把执行器路径指向函数。在命令式框架下则只需要导入执行器函数挂上注解和权限标记。迁移过程中最常见的坑是返回格式不兼容。有的框架要求Agent工具必须返回字符串有的框架要求必须是结构化字典对象。这种差异应该由适配层负责转换而不是去改技能内部逻辑。把这点想通以后再往第三套框架迁移的时候新增工作量就只剩下一个适配器了。6. 三个真实踩坑记录描述抽象、过度复用与上下文污染6.1 描述写得太像人话Agent反而不认识这是我早期技能库上线时最常出现的问题。当时我觉得技能描述应该写得像产品文案要优雅、完整、有说服力。结果有一次Agent面对一个明显应该触发表格透视技能的需求居然完全绕过了技能自己凭空生成了一套不存在的透视结果。排查了很久才发现原因就是技能描述里写的是对数据进行多维度洞察并生成透视表格模型压根没把这句漂亮话和实际操作的数据透视表对应起来。后来我换成了极其朴素的写法当用户要求对二维表格做按行、按列汇总计算时使用本技能。描述里的每一个词都有对应的可检测行为。从那之后这个技能的匹配率大幅提升。技能描述不是传播文案它是给模型做意图识别的路标越直白越好。6.2 过度复用导致的责任不清技能库建设到后期团队里开始流行复用一切的倾向。有人觉得既然发送邮件在很多流程里都用到那就直接在技能库里做一个通用的通信与通知技能把所有消息发送能力都塞里面。结果这个技能上线后问题不断用户只是要发一封简单邮件模型却触发了复杂的通信与通知流程附带了一堆无关检查。更糟糕的是后续在消息通知场景里想改样式却发现改这个技能会同时影响邮件流程和站内信流程牵一发而动全身。最后我把这个通用技能拆成了发送邮件、发送站内通知、生成通知摘要三个独立技能各自维护各自的模板和规则。拆完之后复用反而变高效了——因为每个技能都变成了最小单元组合成本远低于整体修改的成本。6.3 上下文污染技能内部输出主对话最后这个坑比较隐蔽但杀伤力很大。有一次我给某个技能加了过程可视化的功能让它在执行过程中输出日志本来是为了方便调试结果这些日志没有做隔离直接暴露在了主对话上下文里。模型在下一次回复时被日志中的中间数据带偏了。比如它看到日志里有一条清洗后剩余132条记录在下一次用户问题里就自作聪明地引用这个数字实际与当前问题毫无关系。这就是典型的上下文污染问题——技能内部的中间计算信息不应该让外部看到。找到原因后我的解决方案是设定清晰的内部状态与对外返回分离规则技能执行的中间变量全部放在内部上下文窗口只有最终结果和必要的完成标记对外可见。如果确实需要让Agent知道自己执行过什么也只返回一个小型摘要对象包含步骤列表和结果路径不含中间计算细节。这个坑也让我养成了一个习惯任何技能的调试日志都要有一个debug开关且默认关闭。在排查问题时临时打开排查完必须复位避免日志内容长期混入正常的会话记录里。回到开头那句话Agent能不能成为生产力工具很大程度上取决于它有没有一只靠谱的手而agent-skills就是这只看手的骨架和肌肉。我越是深入做技能库越觉得做这件事的最大门槛不是写代码而是把你日常做事的方法彻彻底底想清楚——边界是什么、步骤是什么、怎么算成功、出错怎么办。把这些想明白了写技能就是顺水推舟的事想不明白再多的框架和工具也救不了。最后再分享一个小技巧技能库上线之后定期回头审视一下哪些技能被高频触发、哪些技能一次都没被用到。前者说明你做对了后者说明它可能和真实需求脱节了——该改描述改描述该砍掉就砍掉技能库和任何产品一样需要做减法而不是一味堆功能。