做Agent应用落地到现在我最深的体会是模型本身越来越聪明但业务方真正关心的从来不是“它聪不聪明”而是“让它办一件具体的事能不能每次都办得同样好”。这个“同样好”跟提示词有关系但关系没那么大。真正拉开差距的是把那些反复验证过的做法固化下来让Agent在碰到对应场景时能直接调用——这正是agent-skills这个项目想解决的核心问题。简单说它给Agent做了一层“技能层”让模型不再是每次靠临场发挥去猜怎么做而是调用一套被测试过、被校准过的专业动作去完成任务。这篇文章把我从项目立项、技能体系设计、落地实现到生产环境踩坑的完整过程整理出来适合正在做智能体应用、自动化流程或平台型产品的同学参考。无论你是自己想搭一套Agent技能库还是只想搞清楚“技能、工具、插件、工作流”这些概念到底有什么区别这篇都能给你一个可以参考的答案。1. 项目定位Agent缺的不是聪明是“手艺”1.1 为什么要在“技能”这一层做抽象先讲一个场景。你给模型一段合同让它抽出付款条款和违约条件。第一次抽得不错第二次换了表述它就漏了字段第三次你把提示词改得更详细结果它开始把无关的条款也抽进来。你会发现模型的单次能力是够的但稳定性跟不上。问题不在模型而在于你每次都在让它“重新即兴表演”。技能层的价值就在这里。它不是再写一段更长的提示词而是把“抽合同要素”这件事拆成一套固定的动作序列文本清洗、分块抽取、字段校验、矛盾修正、结果格式化。每一步都有明确的执行方式和验收标准模型在中间扮演的是决策者而非自由发挥者。这样一次写好的流程可以被复用到所有合同场景而不是每个合同都重新调教一遍。这个抽象带来的第二个好处是权限和风险可控。技能是一个有边界的载体它知道自己的输入是什么、输出是什么、能碰哪些数据、不能碰哪些操作。这让安全策略能够落在技能层而不是靠提示词里的“你小心一点不要删除文件”。对于任何要接入生产环境的Agent场景这一点几乎决定了项目能不能过审批。还有一个容易被忽视的收益技能可以作为评测单元。你可以给每个技能单独建测试集单独量准确率单独做回归。相比对着一整个Agent系统黑盒测试技能层的评估要细得多也更容易发现哪里退化。这个能力在持续迭代阶段是保命的。1.2 技能和工具、插件、工作流到底有什么区别我接触过不少团队技能、工具、插件、工作流这四个词混着用结果架构也混成一团。这里有必要把边界划清楚。工具是最基础的单位通常是一次动作比如发送HTTP请求、读写数据库、给图片压缩。工具没有业务目标它只是能力。插件是运行时注入机制指在模型上下文中增加能力包、提示词或工具集。插件更像部署形态解决的是“怎么把能力装进去”的问题。工作流是固定编排它把多个步骤按顺序或条件串起来用户不参与决策流程是写死的。适合表单处理、定时任务这类确定性场景。技能处在它们之间。技能以业务目标为导向内部可以调用多个工具也可以包含模型推理但最终是否调用、怎么调用由模型基于输入和上下文决定。用一句话概括工具是零件插件是包装盒工作流是流水线技能是手艺人的整套手法——既知道目标又知道流程还能灵活处理意外。这个区别在架构上会直接反映出来。技能如果仅仅是工具集合那它退化成工作流如果仅仅是提示词包装那它退化成插件。真正合格的技能一定要包含触发判断、输入校验、执行编排、输出校验、错误恢复这几层缺一不可。2. 技能体系的骨架设计与关键决策2.1 一个技能包的四个组成件一个技能在设计上拆成四个部分我在实际开发中一直用这个结构边界很清晰。第一个是技能元信息。包括技能名称、版本号、命名空间、技能描述、触发条件、不适用场景列表。这块不仅是给人看的更重要的是给模型看的模型要靠这段描述来决定“当前场景要不要调用这个技能”。所以描述不能只写功能还要写限制明确说“这个技能不做什么”。第二个是输入输出Schema。输入要定义清楚字段类型、必填项、取值范围输出要有明确的返回结构。我用的是与JSON Schema兼容的定义格式让每个技能可以独立做参数校验。这一步不能偷懒Agent场景里很多低级错误都源于模型传入了不符合预期的参数而校验能把大部分错误挡在外层。第三个是执行体。执行体可以是一段代码、一组内部工具调用序列也可以是一个混合了代码步骤和模型步骤的编排逻辑。执行体是技能的手艺部分负责真正把事办好。这里要特别注意执行体内部是否允许再次调用模型。允许的话要设好模型调用的超时、重试和轮次上限防止技能执行时拖垮整个Agent。第四个是安全边界。包括技能能访问哪些数据源、能发起哪些外部请求、能执行哪些写操作、是否需要人工审批、日志记录级别等。我倾向于把安全边界写成一个独立的策略块而不是散落在代码里这样审计和维护都容易。这四个件的关系可以想象成一张技能卡片元信息是卡面Schema是插槽形状执行体是背后的机械结构安全边界是保险丝。2.2 技能的分类、注册与发现机制技能多了以后第二个要解决的是分类和发现。我按任务性质把技能分成四类每一类在实现上差异很大。数据获取类技能负责从外部系统读取信息比如查库存、查订单、拉取汇率。这类技能的特点是对实时性要求高输出格式标准通常以只读接口为主。计算分析类技能负责对已有数据做处理比如汇总周报、做数据对比、生成图表配置。这类技能一般不会主动访问外部系统执行体里以代码和模型推理为主。事务操作类技能负责改变系统状态比如创建工单、发起审批、更新记录。这类技能安全要求最高默认需要人工确认或操作留痕。内容生成类技能负责产出文档、邮件、代码等文本类结果。这类技能的难点在风格一致性和格式约束通常需要额外的模板层和规则校验。注册与发现方面我搭了一个轻量的技能仓库所有技能都通过统一接口注册进去。Agent启动时只拉取技能摘要列表实际调用时再按需加载完整配置。发现机制上我做了语义检索模型的工具选择器会根据任务描述检索候选技能再结合技能描述做择优。这里有个容易踩的坑如果所有技能描述都写成“处理各种任务”模型就完全失去选择依据了。描述一定要写得像给同事交代工作“你去帮我做这个注意这类情况不要碰。”越精确路由越准。2.3 版本管理、灰度发布与依赖隔离技能和代码一样是持续演化的。一个技能改了抽取规则可能影响上百个Agent实例。所以技能必须有自己的版本管理。我做版本管理的核心原则是技能标识由命名空间、技能名、版本号三段组成。任何行为变化哪怕是改了一行提示词都要发布新版本不允许原地修改。线上Agent固定引用某个版本新版本先走灰度在小流量Agent上跑一段时间对比效果指标后再全量。灰度发布这件事在Agent场景里容易被忽略因为大家习惯把它当成普通代码来发。但实际上技能变更影响的不是接口行为而是模型决策行为影响面远大于普通代码修改。同一版本的技能在不同模型版本上的效果也会不一样所以我的灰度方案里还包含模型版本信息技能版本和模型版本一起组合测试。依赖隔离也很重要。一个技能内部可能依赖多个内部服务不同技能之间要有独立的超时配置和失败降级策略。我不会让一个技能去依赖另一个技能的执行结果除非做成显式的技能组合编排避免整条链路出现隐式环。否则线上出现循环调用的时候排查会非常痛苦。3. 实操手写一个可落地的技能包3.1 选一个好场景以合同关键要素抽取为例纸上谈兵告一段落我以实际项目中做过的一个“合同关键要素抽取”技能为例把从设计到上线的完整过程过一遍。选这个场景有几个原因。第一合同文本格式多样恰好能体现技能相对单次提示词的优势。第二合同要素抽取的结果是结构化数据便于做回归评测。第三这个场景有明确的安全要求不能把合同全文随意传给外部接口必须做到本地清洗和脱敏。业务方最初的诉求很朴素每天收到几十份合同需要人工抽出签约方、合同金额、付款条件、违约责任、合同期限这几个关键字段。人工做太慢而且容易漏。他们试过直接把合同全文丢给模型问答案效果飘忽不定后来找到我们希望做成一个可复用、可监控的能力。3.2 编写技能描述与参数Schema技能描述是整个技能的灵魂。我第一版写得很简单抽取合同关键要素。后来发现模型经常在非合同文档上也触发它比如拿招聘启事问它也能给你抽出“签约方”非常荒谬。原因就是描述里没有写排除情况。最终版本的描述我改成了带触发条件和负面清单的风格技能名称contract_entity_extract 技能描述用于从中文商务合同文本中抽取关键要素包括签约方、合同期限、合同金额、付款条件、违约责任。 触发条件 - 输入文本明确包含合同、协议、契约等字样或上下文属于商务签约场景。 不适用场景 - 新闻、公告、招聘信息、技术文档、会议纪要等非合同文本。 - 合同扫描件尚未完成OCR输入为图片的场合请先调用OCR技能。 - 需要提供法律意见或合同合规建议的场合本技能仅做字段抽取不提供判断。这个描述的作用是让模型的工具选择器知道什么情况下用、什么情况下别用。你越界去抽非合同文本表面上也能抽出内容但那不是技能该做的事只会在生产环境制造错误数据。参数Schema我用JSON Schema格式定义字段包括source_text、require_provisions、languages三个。其中source_text必填require_provisions允许调用方指定只抽取某些字段languages限制抽取语言。没有把输出格式写死在调用方传参里因为输出结构由技能内部统一决定避免同样技能被不同参数模式调用后返回各式各样的结构。3.3 实现执行逻辑与安全护栏这一版技能的执行体由四个阶段构成。文本清洗阶段先把输入文本做规范化处理去掉多余空格、统一换行符、识别段落标题。同时做一次敏感信息检测把身份证号、银行卡号等字段打码后续所有处理都在脱敏文本上进行。分段抽取阶段是核心。合同文本通常很长一次性塞给模型容易丢失细节还容易触发长文本失效。我把文本按条款标题切分成多个分段每次只让模型抽取当前分段相关的字段最后合并。这里有个关键参数分段大小。我测试下来中文合同按条款粒度切分最稳定大概每个分段控制在1200字以内超过就继续拆分同时保留条款编号用于回溯。规则校验阶段负责检查模型输出的合理性。例如合同金额是否为正数、日期格式是否合法、签约方字段是否为空。如果校验不通过技能会带着校验失败原因进行一次重抽取把错误字段和失败原因都告诉模型让它重新生成。这一步显著提升了最终准确率。结构输出阶段把所有字段汇总成统一结构附带每个字段在原文中的定位引用方便人工复核。所有处理过程都记录审计日志并且整个技能没有任何写操作权限无法发起对外请求无法写入业务数据库只能返回结构化结果。安全边界里我还专门加了一条技能执行全程不允许联网。合同内容高度敏感如果模型在抽取过程中可以联网等于把合同内容暴露给第三方服务这在不少行业是直接踩红线的行为。3.4 评估集合与上线验证技能写完后我没有直接接进Agent而是先做了评估集。我找业务方要了历史合同中签过保密协议的50份脱敏文档人工标注出所有目标字段做成第一版标准答案集。然后跑一遍技能统计每个字段的准确率和召回率记下失败样本。第一轮测试结果并不理想。金额抽取的准确率只有82%主要失败原因集中在大小写金额混用、合同里同时出现预付款和尾款的情况。我针对这两类失败在分段抽取阶段的提示模板里增加了明确指令“如果合同中有多个金额条款必须分别列出并注明所属场景不得合并。”同时在校验阶段增加了一条规则金额字段必须带币种和大小写一致检查。调整后第二轮准确率到了94%。94%看似不错但仍然不够。我把剩余失败样本归类后发现大部分失败来自行业黑话比如某个特定领域的计费方式缩写模型不认。这个问题的本质不是技能设计能完全解决的还需要领域词典的配套建设。于是我在技能执行体中预留了领域词典注入位业务方可以把自定义术语映射导入技能首次加载时自动扩展提示模板。上线时我采用了灰度策略。先在一个低风险Agent上接入新技能指定该Agent只处理测试环境合同跑一周并对比人工复核日志。确认技能抽取结果中需人工修正的比例低于阈值后才逐步放开到生产环境的合同处理Agent。整套上线流程走下来最重要的一条经验是技能上线前一定要有可重复运行的评估命令任何改动都能在半小时内重跑一遍评估集出报告这个能力在后面持续迭代时价值巨大。4. 生产环境中踩过的坑和排查方法4.1 技能被误用描述“完美”反而糟糕我在2.2里提到过技能描述影响路由这里讲一个具体教训。有段时间我们给一个“周报生成”技能写了非常详细的能力介绍包括“能自动统计数据、能格式化输出、能识别亮点项目、能写OKR总结”。结果模型在用户只说“帮我写个周报”的时候就把所有能力都激活了一遍生成了一个逻辑混乱的长篇报告。排查后发现问题出在描述写法上。描述里把能力写得越多模型越倾向全量调用因为它无法自行判断哪些能力在这个场景是需要的。改成能力分层后问题解决描述只写“聚合工作数据并生成结构化周报”把统计方法、格式细节放到了执行体内部。模型需要做的决策只有一个——是否调用至于调用后怎么做由技能自己控制。这是技能设计里一个很反直觉的点描述要克制不能“太能干”。这类问题的排查方法也不复杂。翻Agent运行日志看模型每次调用技能前的思考路径。如果大量调用发生在不合适的场景大概率是描述中的触发条件写宽了或者反面清单缺失。把误调用的样本收集起来逐条反推是描述哪句话导致了误判比对着模型瞎调参数有效得多。4.2 技能说明挤爆上下文怎么办技能数量一多又一个问题冒出来了每个技能的元信息和描述都要占用上下文。早期我们把所有技能完整信息一次性注入上下文大约20多个技能后光技能说明就吃掉了一半上下文窗口留给主任务的空间所剩无几Agent的推理质量肉眼可见地下降。解决方案是两级注入。第一级只注入每个技能的名称、一句话描述、适用标签总量控制在几百字以内。模型根据任务判断需要哪个技能后再按需加载该技能的完整说明。实现上就是一个“技能只读接口”Agent通过函数调用拉取指定技能的详细定义带进后续轮次。这个方案还带来了额外的好处即使技能数量扩展到上百个Agent核心上下文的占用依然稳定。第一级摘要必须写得极其精炼目的不是让人看懂而是让模型能在几十毫秒内完成筛选。我把每个技能的摘要都压到30字以内像写消息通知标题一样写技能摘要。两级注入也有失效场景。如果Agent任务是一次性完成多个技能的组合比如“先抽合同要素再生成摘要”那就要在任务开始前把两个技能都拉取进来否则第二次加载时主上下文已经被前面的输出占满。我的做法是给每个技能声明依赖标签技能选择器在做路由时同时考虑当前任务涉及的全部技能集合一次性加载。4.3 技能冲突、覆盖与路由错乱当不同业务线都在往平台里注册技能时冲突几乎无法避免。我遇到过最典型的一个情况两个团队分别注册了“数据汇总”技能名字一样、描述相似但内部逻辑完全不同一个偏向财务口径一个偏向运营口径。模型随机命中其中一个生成的汇总结果口径不一致业务方直接投诉。我的解决办法是引入命名空间和显式路由规则。技能全名变成“财务域/数据汇总/v2”和“运营域/数据汇总/v1”在技能摘要里强制标注适用域。同时增加一个前置路由技能专门负责判断当前任务的业务域再根据域信息选择合适的汇总技能。这个改完后路由错误率从之前的21%降到了2%以内。还有一个隐蔽的坑是技能“覆盖”。某个技能升级后旧版本还在缓存中模型迭代时偶尔加载到旧版本的描述导致行为不一致。这里没有妙招就是把技能缓存策略做严格版本号变化时强制刷新旧缓存同时所有技能的ID必须携带版本号禁止出现裸技能名。4.4 多Agent共享技能时的权限治理技能库建好之后自然会有多个Agent共享。这时候权限治理就成了最容易翻车的地方。我原先的做法很粗暴所有技能对所有Agent开放。后来一个内部Agent被诱导重复调用某个写操作技能差点把测试环境的脏数据写进生产库。教训很直接技能权限不能默认全开而是默认全关。每个Agent在创建时声明自己需要使用哪些技能技能分配走审批流程。同一技能在不同Agent下可以有不同的安全策略比如高权限Agent调用时不需要审批低权限Agent调用时必须经过人工确认才能执行写操作。另一个细节是技能执行时的身份标识。每次技能调用都要携带来源Agent的标识这样所有审计日志能追溯到具体Agent实例。我们把“谁调的、调的哪个技能、传了什么参数、返回了什么结果、耗时多久”全部结构化记录出了问题直接按链路回放排查效率比靠日志关键字搜索高一个数量级。这个技术栈不复杂但收益非常大强烈建议每个做Agent平台的人都尽早铺上。5. 效果度量与能力沉淀的复盘5.1 衡量一个技能值不值得留下技能开发多了以后我开始面对一个更现实的问题如何判断某个技能到底有没有价值值不值得维护。靠感觉是不行的我用五类指标来度量。调用成功率是最基础的指技能在执行过程中没有报错、顺利返回的次数占比。我按周统计低于90%的技能进入待优化列表。任务达成率更严格要求结果经过规则校验后所有必填字段都有效。合同抽取技能我主要看这个指标当前稳定在97%以上。返工率反映结果质量即业务方收到技能产出后有多少比例需要人工修改。返工率高于20%的技能即使调用了很多次本质上还是在给业务制造负担我会标记为高优化优先级。资源消耗指技能执行过程中的Token消耗、接口调用次数、单次耗时。这个指标不是越低越好但需要有基准。如果一个技能单次消耗的Token明显高于同类型技能说明执行体里可能存在无效循环或过度重试。人机干预比指技能在运行过程中触发人工审批或介入的频率。这个指标对事务操作类技能特别关键频率太高说明安全策略过严或技能本身不够可信频率太低则可能存在权限失控风险。技能度量我做成了一张周级趋势表每个技能一张卡片五个指标一目了然。这里推荐团队至少一个月复盘一次重点看趋势而非绝对值。某个技能可能整体准确率不高但趋势在持续上升说明迭代方向是对的值得继续投入。5.2 让每次高质量调用变成团队的资产这里的最后一层思考是技能的价值不只是被调用还包括在调用中沉淀下来的东西。每次成功执行后输入样本和输出结果都应该进入样本库。这个样本库不需要人工标注基于规则校验判断“成功”即可质量足够用作后续评估回归。我自己在项目后半段的一个习惯是每两周从样本库里随机抽一批成功案例做人工复检。人工复检和规则校验的结论经常会不一样比如规则校验判为成功但人工看来结果明显不合理。这些差异就是技能改进的最好线索。我有一句经常对团队说的话评估集不是一次建完就一劳永逸的它必须跟着真实世界的语料一起生长。关于技能的生命周期我的经验是允许技能死亡。有些技能可能一开始被很多Agent频繁调用后来业务调整调用量掉到个位数。这时候果断下线比继续维护更划算否则你还要为它承担版本检查、缓存刷新、权限审批等一堆固定成本。下线不是删除而是把技能标记为“归档保留”它的评估集和样本库留在仓库里未来如果业务回归能用少于原来30%的时间恢复这个能力。我自己在把agent-skills这个项目推进到当前阶段后的一个感受是做技能层做的不只是技术更是把团队的实践经验工程化。每一次踩坑、修正、补样本都是在把一个曾经只存在于某个老员工脑子里的操作套路变成整个系统里可复用、可度量、可追溯的正式资产。这件事坚持做下来效果不是某次评估指标提升一点而是整个Agent体系的稳定性会以肉眼可见的速度改善——那种“这周好像没那么折腾了”的感觉就是这个体系开始成熟了的信号。