如果只让我用一个词概括Agent工程里最容易被忽视、却最能拉开项目差距的部分我会选“技能层”。聊agent-skills之前先说个场景同样是让LLM写一段数据清洗脚本有的Agent每次都在试错、报错、改到超时有的Agent一次就能给出可运行代码差别不在于模型强弱而在于后者把“数据清洗”沉淀成了可复用的技能模块再调用时不是从零推理而是“取出来、填参数、执行”。想让你手下的Agent从“能问答”进化到“能干活”而且越干越稳整个系统的设计核心就在技能库。这篇文章我把我自己搭过、也拆过好几套Agent技能系统的经验理了一遍从技能怎么拆、库怎么建、Agent怎么选技能、到上线后必踩的坑一次性写清楚。1. 技能层到底是什么先想明白Agent为什么需要它最近很多关于Agent的讨论都在强调“规划能力”和“工具调用”但实际跑过项目就会知道纯靠模型自由发挥去完成一个稍复杂的任务结果极其不稳定。模型今天心情好能给你拆出五步明天同样的指令可能只走两步就“自我感觉良好”地停了。1.1 稳定性的来源把推理工作变成查表和取模板人类做事也是这个逻辑一个老工程师写SQL不用每次重新推导语法因为他脑子里存了模板一个老设计师做海报不会每次都重新研究构图因为他调用了自己的“技能记忆”。Agent技能层就是在做这件事——把高频、稳定、可复用的操作流程从模型每一轮的随机推理中剥离出来变成一套有明确输入输出、有确定性实现的模块。实现方式并不神秘技能库本质上是一个带元数据的能力集合。每个技能定义了名称、描述、参数结构、执行方式本地函数调用、HTTP请求、外部脚本等。Agent在接到任务时先判断需要哪些技能再按需调用和组合。1.2 一个直观的对比有技能层和无技能层的差距我把同一个需求分别丢给两套系统做过对比需求是“读取销售明细表按月份汇总各类商品的销售额输出CSV”。无技能层的那套系统模型自己编代码、自己执行、自己改错遇到字段名不匹配就反复猜整个过程大概率超过十分钟有技能层的系统因为已经注册了一个aggregate_data技能模型只需要把“销售明细表”和“月份/商品/销售额”这几个字段映射到参数上其他全部由技能内部实现接管。这个差距在单次任务上已经很明显放在批量任务里就是数量级的差异。用“技能化”的方式约束Agent不是限制它的能力而是把它的聪明用在决定“做什么”上把机械的“怎么做”交给稳定层。2. 技能拆分的正确姿势原子技能与复合技能的分工很多人在最开始把技能设计成一个“大杂烩”一个技能里既要做数据清洗、又要做统计、还要生成报告。结果就是技能的描述越写越长、参数越设计越复杂Agent根本搞不清该在什么时候选它。技能拆得好不好决定Agent能不能正确路由。2.1 原子技能最小的可执行单元原子技能对应一个逻辑上不可再拆的操作。比如“读取CSV文件并返回标准化DataFrame”“发送邮件”“调用某个API”“执行一段SQL”。它的特点是输入输出明确内部无歧义可以被单独测试。我习惯用一个自检标准如果一个技能的文档和测试用例加起来超过一定复杂度或者它的名称里需要加上多个动词才能说清楚就说明它拆得不够细。比如“数据分析”这个技能就是一个典型的坏命名它可以是清洗、聚合、可视化、假设检验等好几个原子技能的组合。2.2 复合技能原子技能的编排逻辑复合技能解决的是一类反复出现的典型任务流程。比如“生成月度数据报告”可以编排为三步读取各渠道数据源、清洗与合并、按模板生成报告文件。每一个子步骤都指向一个原子技能复合技能本身不实现业务逻辑只负责编排顺序和传递中间结果。从工程角度看复合技能更像一张流程图但它不是一个有向无环图式的代码实现而是用模板描述“调用哪些技能、按什么顺序、如何做错误处理”。Agent运行时仍然需要根据实际情况微调但技能层的约束会让它的表现收敛在合理范围内。2.3 命名和参数设计给Agent一份不会误解的说明书技能名要像API文档里的好函数名一样自解释。我把实际项目中踩过的命名坑列一下问题反例建议动词模糊process、handle用generate_monthly_report这类动宾结构名词缺失get_data明确数据源get_sales_from_database中英混合统计data统一语言建议全英文或全中文上下文过窄read_current_file技能应保持通用文件名作为参数传入参数设计方面最核心的东西是每个参数的描述。模型不是程序员它看到file_path不一定会理解这是个绝对路径还是相对路径。参数描述要写清楚类型、格式、约束条件和示例值。我见过的失败案例中有相当比例是本该传csv文件路径、模型却传了json字符串根因就是参数的JSON Schema描述没写够。3. 技能库工程化落地注册、存储、检索一个都不能少技能拆完下一步就是把它们组织成可以被Agent高效访问的系统。这里说的不只是“把函数放进一个目录”而是要考虑整个生命周期技能怎么注册、用什么结构存储、Agent用的时候怎么检索到正确的那个。3.1 技能注册表所有技能的“身份证”中心每种技能都需要一条注册记录来承载元数据。我常用的注册表结构大致包含这些字段{ name: aggregate_sales_by_month, description: 按指定时间维度如月份/季度汇总销售明细表的销售额并输出标准CSV。适合用于销售数据分析。, parameters: { type: object, properties: { file_path: { type: string, description: 销售明细CSV文件的绝对路径必须包含date列和amount列。 }, group_by: { type: string, enum: [month, quarter, year], description: 汇总的时间粒度。 } }, required: [file_path, group_by] }, execute_type: local_function, entry: data_skills.aggregate_sales, version: 1.2.0, tags: [data, sales, report] }这里每项都有讲究。description是模型判断“要不要选这个技能”的依据必须强调“解决什么问题”和“适用场景”parameters必须用严格模式模型生成的参数是否合法就靠它校验execute_type决定运行时怎么加载这个技能本地函数还是HTTP调用。版本号不是注释装饰技能逻辑升级后Agent可能会暂存旧技能的调用方式版本管理能帮助排查线上问题。3.2 存储与加载选对容器别为炫技买单小型项目一套本地目录加JSON文件足够把注册信息以skills/目录组织每次Agent构建时把技能说明送进上下文即可。中型项目建议用数据库存注册表技能代码可以保持为Python/Node模块但注册信息用表管理方便做权限控制和审计。当技能数量超过百级一个容易忽略的问题是“加载哪些技能”。全量加载必然把系统上下文撑爆正确做法是分层加载固定带上少量基座技能对话处理、文件读写再根据任务通过检索动态拉取可能有用的技能列表。这个“基座动态检索”的组合是我在实际项目中验证过最稳的模式。3.3 检索方案从笨办法到混合召回最朴实的检索方式就是“用户发一段任务描述把技能名称和描述放入向量库做top K召回”。但纯向量检索在技能名和描述文本较短的情况下效果一般我建议用混合检索BM25做关键词召回向量做语义召回再把两个候选集做融合排序。另外一个在检索阶段经常被忽略的质量信号调用历史。同一个Agent在过去的会话里反复使用某些技能说明它和当前任务类型高度相关可以给历史高频技能加分。别小看这个信号在真实场景里它经常比向量相似度更可靠毕竟“用户以前常用”本身就是很强的任务相关性证据。4. Agent选技能和填参数的完整闭环从路由到执行技能库建得再漂亮最后都要过“Agent能不能在合适时刻选中正确技能、填入合法参数”这一关。这一环节我开始以为是模型能力问题做多了发现工程手段能解决大半。4.1 显式路由优于让模型自由发挥项目早期我试过“把所有技能说明全部塞进系统提示词让模型自行选择”。技能少还能凑合用技能一多模型经常把两个描述相近的技能搞混。后来我把选择过程拆成显式两步先用检索层缩小候选集再把候选集送给模型做二次判断。显式路由的意义在于可观测、可干预。模型选错技能时系统能明确记录“候选集有哪几个、选中了哪个、为什么选”这些日志是后续调优检索质量和技能描述的宝贵材料。我曾经通过分析这类日志发现一个技能被反复漏选的原因是其描述中缺少了核心业务名词补上一个词后选择准确率提升了十几个百分点。4.2 参数填充让模型少编让模式多补模型在参数填充上最容易犯两类错误一类是格式错误比如把数组参数传成JSON字符串另一类是语义错误比如把“4月1日”填成“4月1日00:00:00”。格式错误靠JSON Schema严格校验可以拦下语义错误则需要技能内部做一层宽容处理。我常用的做法是“模型给原始值技能做归一化”。举个例子日期类参数允许接收2024年4月或2024-04技能内部统一转成标准格式。这样Agent不必学习每个技能期望的精确格式只需要把信息传对剩下的交给技能实体处理。这个设计大大降低了模型出错的概率也让技能对模型更“友好”。4.3 失败重试与熔断不能说技能库无用更不能死循环技能执行失败分两种技能内部错误和参数错误。参数错误应该重试让模型修改参数后再次调用技能内部错误要立刻终止并向上汇报而不是让模型反复重试。判断依据是错误消息的类型标签这一点必须在技能开发规范中定死。熔断设计也要有。当同一技能连续失败超过阈值系统应暂时将技能标记为“暂停”并转用人工或备用流程。尤其自动化任务长期跑的时候没有熔断就可能出现重复扣费、重复发消息等事故。我在生产环境遭遇过这类问题后把所有技能的调用都归到统一执行器上集中管理重试策略、超时设定和熔断状态。5. 从“练”到“会”让Agent把经验沉淀成新技能技能库是有生命力的它必须支持增长。除了开发者手动写技能Agent在解决新问题时产生的有效方法也应该能被沉淀下来。这就是很多人感兴趣的“Agent自己学会新技能”的方向。5.1 过程捕捉把执行路径变成技能草稿我曾经搭建过一个简单的技能沉淀管线Agent完成一次成功任务后系统把它的完整执行轨迹保存下来包括用到了哪些工具、按什么顺序调用、传入了什么参数、中间经过了哪些判断。随后有专门的模块把轨迹抽象成“步骤模板”把具体参数替换为参数占位符就得到了一份技能草稿。这个流程的难点在“抽象化”。简单照抄历史轨迹会让技能过于死板真正有用的抽象要能区分哪些步骤是固定流程、哪些是本次任务偶然的选择。我的做法是让多个相似轨迹交叉比对把重合度高的部分提出来作为固定骨架分歧较大的部分则设计成可选分支。5.2 校验与发布草稿不能直接上线自动生成的技能草稿在投入使用前必须经过一套回归验证用一小批历史任务跑一遍确认草稿技能能覆盖其中大部分场景且输出不被破坏。没有校验直接上线的后果我在某个业务Agent上体验过自动生成的“客户分群”技能看似合理却因为过期业务规则在上线当天就做出了错误分群结果。因此我的技能仓库设有“草稿区”和“正式区”两个隔离区域。草稿技能仅供Agent在低风险任务中试用准确率达标后由人审确认再升入正式区。自动沉淀是很酷的技术但在涉及真实业务决策时保留人工确认环节从来都不是“倒退”而是一种必要的安全阀。5.3 技能版本演进改对一个描述胜过改十行代码技能上线后也不是一劳永逸。我在维护技能库时有一个系统性方法定期统计每个技能的被调用次数、成功率、参数修改频率排在末尾的技能基本是“无效资产”要么合并要么下架。排在前面的技能则要关注模型选择是否稳定偶尔出现“该选它的场景选了个替代技能”的行为通常是描述文本产生了歧义。这类调优用A/B对照来做很有效对同一个技能写两个不同风格的描述版本分别应用到两批镜像流量中以任务成功率、平均会话轮数、上下文消耗为指标来比较。改技能描述跟改代码一样要讲究可衡量不能凭感觉拍板。6. 我把一套最小技能系统跑通后架构、评价与心得做现状总结之前先把可复制的整体结构说清楚。你不需要昂贵的框架一套Python环境、一个向量检索库、一个SQLite表就能构建最简技能系统。6.1 最小技能系统的四个组成模块第一个是技能注册服务负责技能的入库、更新、上下架第二个是检索服务接收任务描述输出候选技能列表第三个是执行器负责参数校验、技能调用、错误分类和重试第四个是审计日志记录每次技能的选择、参数、耗时、结果。四个模块各司其职组合起来就是一套完整闭环。核心调用流程可以这样描述任务请求进入先由检索服务取出候选技能再交给模型做最终选择确认后生成参数通过执行器调用技能实体技能结果返回后模型把结果加工成最终答案。我建议为每个阶段输出结构化日志字段这不仅是调试工具也是后续训练“技能选择模型”的数据来源。6.2 评价技能系统不要只看“一次成功”我把评价指标分成两类效率类和质量类。效率类包括技能调用命中率、平均单任务耗时、上下文消耗质量类包括任务成功率、结果人工修正率、用户反馈评分。单看每轮成功与否其实是一种误导有时候模型选错了技能但任务结果碰巧能看这样的场次也要纳入“选择错误”统计。另外坚持做“负样本积累”。每次模型选错技能或者填错参数都要把当时对话截取出来标出正确答案。积累到一定量级这些样本可以直接微调一个本地小模型来做技能路由是脱离大模型API高延迟和成本效应的可行路径。6.3 最后聊几句踩坑体会第一永远不要在系统提示词里塞全量技能说明。上下文长度有限技能多了模型反而选择困难。第二技能内部实现要写得足够固执已经在技能里确定的分支判断不要留给模型自由发挥否则就失去了技能化的意义。第三不要一开始就追求让Agent自动沉淀技能先手动把二三十个原子技能建好并稳定跑通再上自动沉淀机制效果远好于从零启动的半自动状态。Agent项目越往后做越会发现模型的推理能力只是引擎技能库才是真正让引擎做有用功的传动系统。先把技能做“稳”再追求“多”这条路我验证过可行希望你少踩几个我当年的坑。