过去半年我一直在和一个非常具体的问题较劲为什么同一个大模型在对话框里看起来什么都会放进agent框架里就经常把事情搞砸。排掉模型能力本身的差异之后剩下的变量几乎都集中在agent-skills这一层——也就是你喂给模型的那组技能定义到底靠不靠谱。与其说agent是“会调用工具的模型”不如说它是一套由技能组成的操作系统技能的边界、描述质量和调用约定直接决定了agent的上限。我见过太多团队把agent做成“玩具”模型接上两个API就开始演示跑通一个case就宣布“Agent落地”。结果一到长流程、真实数据、多人协作的场景马上原形毕露。核心原因只有一个他们把所有逻辑都塞进了system prompt把“会调用工具”当成了“有技能”。实际上agent-skills更像操作系统里的“可执行程序”它需要明确的输入输出约定、独立的上下文、可验证的效果以及一套围绕它生长的工程体系。这篇文章我把自己在真实项目里积累的设计方法和踩坑经验梳理了一遍重点放在那些文档里不会写、但实战中决定成败的细节上。先说一个我很典型的观察。有位朋友给我看他们agent的对话日志用户问“帮我整理上周的销售周报”agent先调CRM接口拿到数据再接一个PPT生成的工具看起来流程没问题。但最后生成的PPT里图表数据是两套口径——CRM取的是订单金额另一个工具按回款金额算的。问题不在模型也不在单个API而是两个技能之间没有定义清楚数据口径。你给agent装的技能越多这种隐性冲突就越多而大多数团队连“技能”这个概念本身都没建立起来。1. agent-skills的本质给模型一份可执行的“岗位说明书”1.1 技能不是工具也不是提示词先理清几个容易混淆的概念。工具tool是最底层的能力单元比如一个HTTP接口、一个函数、一条SQL查询。提示词prompt是指导模型如何行为的文本。技能skill则是两者的结合体它把工具的使用方法、适用场景、输入输出约定、常见的坑全部封装成一份模型可以反复参考的“操作手册”。我见过最普遍的做法是把技能当成稍微复杂一点的工具描述去写。比如给模型挂一个“查询天气”的函数参数定义为城市和日期然后就算完事了。但这只是工具接入不是技能建设。真正的技能要以“完成一类任务”为单位来设计比如“生成销售周报”它内部可能涉及取数、清洗、计算环比、选择图表类型、生成文本结论等多个步骤每一步都要让模型知道该怎么做、为什么这么做、什么情况不能这么做。你可以把技能想象成给一位新入职的实习生写的SOP。工具清单只告诉他公司有哪些系统而技能文档要告诉他整个任务的完整流程、判断标准和兜底方案。没有这份SOP实习生只能靠猜表现完全看运气。模型也是如此。1.2 技能在agent系统中的位置在落地agent时我习惯把系统分成四层模型层、技能层、编排层、记忆层。模型层是推理引擎编排层负责把任务拆解成步骤并决定调用顺序记忆层保存跨轮对话的上下文和长期知识技能层则承载“每个步骤具体怎么做”的能力。这四层中最容易被低估的就是技能层。很多团队花大量精力调模型、优化编排框架却忽视了技能本身的质量。结果模型再强、编排框架再智能喂给它的技能是含糊的agent的表现一定不稳定。我后来把技能层当作独立产品来做——单独设计、单独测试、单独维护版本设计理念和写CRUD接口完全不同。技能层的关键属性是三件事可发现性模型知道什么时候该用这个技能、可执行性模型知道怎么一步步把技能跑完、可验证性技能跑完之后怎么判断结果质量。如果一个技能在这三方面做到位agent的可靠性会显著提升。2. 技能库设计第一步先定义动作空间再写提示词2.1 动作空间的粒度怎么定设计技能库的第一步不是写提示词而是划定动作空间action space——也就是你的agent一共能执行哪些技能每个技能的边界在哪里。这里面有一个常见的纠结技能应该拆得细一点还是粗一点拆得太细比如“获取当前日期”也算一个技能模型要在大量琐碎的技能里挑选决策负担重而且agent会经常选错拆得太粗比如“执行数据分析”这种包罗万象的技能模型的自由度太高输出不可控。我的经验是遵循“用户意图粒度”来划分。问问自己一个用户如果提出明确需求这个需求被分解后的最小可交付单元是什么“查询天气”算一个“生成周报”也算一个但“打开数据库”就不算——因为数据库本身不构成一个可交付的结果它是中间动作。中间动作不应该暴露给agent做自由选择而应该封装进技能内部。在一次项目中我们需要做一个客服工单处理agent。最初设计了30多个细粒度技能包括“查找用户”“查找订单”“查看物流”“生成回复模板”等。实际跑下来模型经常在简单对话里来回触发两三个技能导致响应延迟高而且技能之间还有重复的逻辑。后来我们把技能合并成“工单上下文速览”“工单解决建议”“话术草拟”“敏感操作提醒”四个同时把查找类的中间动作内聚到每个技能内部。效果一下子好了很多调用次数减少一半准确率还涨了。2.2 把“何时用”写进技能的元信息动作空间划完之后要给每个技能写一份结构化的元信息。这部分在多数框架里都有对应字段比如name、description、parameters但真正重要、又经常被写不好的是description。很多工程师写description时特别敷衍比如“获取订单信息的函数”。模型看到这种描述很难判断它适合用在什么场景、需要填哪些参数、返回什么格式。我推荐的写法是在description里写清楚“适用于什么情况、不适用于什么情况、需要哪些前置条件”。举个例子一个“查询订单状态”的技能description可以写成用于查询客户订单的实时状态。当用户询问“我的订单到哪了”“发货没有”“什么时候能到”这类问题时调用。需要提供订单号或用户ID。如果用户问的是售后退款进度请使用“查询售后进度”技能不要调用本技能。这段描述给模型的信息密度远超过单纯的“查询订单状态”。第一它通过示例的措辞告诉模型触发条件第二它明确了参数的获取方式第三它通过负向指引“如果…请使用…不要调用本技能”减少了错误调用的可能性。2.3 为技能定义一个经验级的小模板经过几轮迭代我形成了一套相对固定的技能模板分享给大家参考技能名称动词开头指向完整任务比如“生成报销统计分析”适用场景什么样的用户请求会触发这个技能至少给两个典型例子禁用场景哪些情况不要用应该转用哪个技能前置条件调用前需要准备好哪些信息没有这些信息时要先进行哪项交互执行步骤按顺序列出核心步骤每步说明意图必要时给示例输出格式最终输出的结构和字段定义最好给一个简化版示例边界与兜底超出能力范围怎么办常见异常处理方式这个模板不是一开始就定好的是在一次失败的落地方案中逼出来的。当时我们只写了“技能名称参数列表”结果agent在复杂的售前咨询场景里频繁选错技能或者选对了却在步骤中漏掉关键环节。后来把上述七个字段补全错误率下降了不少。你可以根据实际场景调整但“适用场景禁用场景执行步骤兜底”这四个字段建议必须保留。3. 技能里的上下文工程操作手册怎么写模型才听话3.1 技能描述不是越详细越好写技能很容易走向另一个极端。我给之前一个项目写的“数据质量检查”技能一度写了3000字把所有edge case全列进去。结果实测发现模型在长上下文里会“淹没”在细节中关键约束反而抓不住。这和大模型注意力机制的特性有关当文档很长时早期的信息在后期的指令遵循中权重会衰减尤其是中间部分。所以我后来的原则是技能描述要“结构化地精简”。把最重要的约束放在开头和结尾中间用清晰的标题分隔每个步骤控制在100字以内尽量用行动导向的短句而不是解释性的长句。比如“过滤掉金额为空的记录”比“为了确保后续统计不受影响我们应该将那些金额字段为空的记录进行过滤”有效得多。3.2 在技能里嵌入“数据契约”刚才提到的周报案例本质上是一个数据口径冲突的问题。要避免这种问题技能与技能之间需要共享一套清晰的数据契约。我在设计技能时会为每个技能定义三个层面的数据规范输入参数、输出结构、依赖字段。以销售周报为例。“取数”技能的输出定义不止是“返回数据”还要标明数据的粒度按天还是按周汇总、金额口径订单金额还是回款金额、时区设置东八区还是UTC、时间范围自然周还是滚动7天。这些信息写进技能文档里模型在处理跨技能任务时才有依据去判断和追问。在一次多技能组合测试中我们发现agent先后调用了“客户分群”和“广告投放分析”两个技能结果生成的报告里“活跃客户”的定义在不同段落中不一样。根因就是两个技能分别拉取了不同数据源且Skill文档里都没有明确“活跃客户”的计算规则。后来我们在每个技能输出结构的data_contract字段里统一标注了依赖指标的定义版本号然后在主提示词里加了一句所有涉及业务指标的地方以指标字典v3为准。这个问题才彻底解决。3.3 状态和记忆技能不应该是“一次性函数”很多agent框架把技能做成无状态的每次调用独立传参、独立返回。这在简单问答里没问题但在多步骤任务里就会出现问题。比如用户先让agent“筛选出价格高于1000元的产品”又说“按销量排序展示前10个”。如果两个请求分别由不同技能处理中间结果没有传递第二个技能就不知道“价格高于1000”这个前置条件。这涉及agent的记忆机制设计但技能层面可以做两件事来缓解。第一技能参数里增加可选的历史条件输入让技能有能力感知前序操作第二技能输出里明确标注“本次处理后的状态”比如是否已过滤、是否已排序方便后续技能判断。这不是最优解但成本最低适合大部分非重度场景。说句实在话业界对agent状态管理还没有统一标准方案不同框架的实现差异也很大。我的建议是在做技能设计时不要假设模型一定记得之前的对话内容。该传的上下文显式地传该声明的假设显式地写永远比指望模型“聪明地记住”更可靠。4. 构建一个可靠技能库的实操方法4.1 从真实日志里挖技能需求而不是拍脑袋很多团队上来就列一堆想当然的技能清单最后发现大量技能没人用或者用户真正需要的技能没覆盖。我推荐的方法是先扒历史对话日志或工单记录把用户的问题聚类找出高频任务场景再据此划分技能。曾经做进销存agent时我们最初设计了“库存预警”“供应商推荐”“自动补货”三个技能觉得功能很完整。但跑了两个月后发现用户问得最多的其实是“某SKU的库存变动历史”和“两个时间段库存对比”——这两个需求我们压根没做成技能。模型只能硬着头皮用其他技能拼凑效果自然不好。后来我们对照日志把技能库调整成用户真实需求驱动的版本满意度才上来。这里有一个可落地的方法把历史问题聚类之后对每一类统计出现频次和用户意图的确定性。高频且意图明确的优先做技能低频但专业性强的可以作为进阶技能慢慢补充意图模糊的宁可让模型向用户澄清也不要做一个模糊的技能去猜。4.2 给技能配上“最小示例”和“黄金路径”技能文档里有一项经常被忽略,就是给模型一段最小可用的输入输出示例。模型是少样本学习的天才一个精心设计的示例比千言万语都有用。我在每个技能里都会放一个示例化场景输入是什么、执行了哪些步骤、最终输出长什么样。这个示例不追求覆盖所有复杂情况而是要呈现一条“黄金路径”——最标准、最理想的一次执行。这相当于告诉模型“你正常完成任务时应该长这样”能显著减少自由发挥的空间。4.3 内测环境必须全量回归技能库一旦超过10个彼此之间的组合效果就会变得不可控。我建议无论团队大小都要建一个技能回归测试集每次修改任何技能都要跑一遍全量测试。这个听上去是很基础的要求但实际操作中很多团队在修改一个技能后只测试这个技能本身导致隐藏的关联问题留到线上才暴露。回归集怎么建选取公司内部真实使用最多的20到30个任务场景每个场景固定一组用户请求和期望结果。跑完结果后不只检查最终答案是否对还要检查技能选择是否正确、调用顺序是否合理、有没有触发危险操作。因为最终答案是模型生成的即使技能调用错了模型也可能凑出一个文本上看似合理的答案从工程角度技能调用路径才是更应关注的。5. 测试技能时我常用的三类方法5.1 单元测试验证单个技能的正确性第一类是对单个技能做独立验证。输入一组涵盖正常、边界、异常三种情况的数据检查技能是否选择了正确的分支、填了正确的参数、返回了符合契约的结果。正常情况考验技能是否跑通主流程边界情况考验技能对参数范围的处理能力异常情况考验兜底逻辑和错误信息是否友好。三类数据尽量维持一定比例比如4:3:3。如果技能本身很复杂还可以细分出“参数解析”“步骤顺序”“输出格式”等维度的检查项为每一项打勾。5.2 组合测试暴露技能之间的隐性冲突第二种也是最容易出问题的测试是组合测试。多个技能在同一个agent里协作时经常出现单独测试发现不了的问题。比如两个技能都定义了“从数据库读取用户信息”但一个用了实时接口一个用了缓存副本数据不一致或者两个技能的错误提示互相矛盾模型判断不了该信哪个。我做过一次组合测试实验把20个技能全部做两两组合构造串联调用场景跑了几十组任务结果发现7处冲突。全是数据字段定义、错误码语义、返回值命名这类细节问题。后来我们在技能文档的头部增加了“数据来源与版本”字段并在组合测试脚本里固定检查这个字段的一致性冲突率明显下降。5.3 用户模拟测试让测试员扮演“难缠用户”第三种是用户模拟测试。找几个不完全了解技能内部设计的同事扮演需求不明确、频繁切换话题、对中间结果反复修改的用户和agent交互。这种测试最能暴露技能在真实对话中的覆盖缺口。我印象很深的一次是模拟用户说“帮我看看这个项目的情况”但没有指定哪个项目。agent当时直接调用了“项目详情查询”技能参数project_id空缺报了错然后傻在那里。后来我们在技能的前置条件里加了明确规则参数缺失时必须向用户追问而不是强行调用。这条规则加进去之后类似场景的成功率提升很大。这段经验也成了我们内测手册里的固定案例。6. 实战中的四大坑和我的避坑方案6.1 坑一把agent-skill做成了“大而全”的万能工具第一个坑是技能范围失控。为了追求“覆盖所有场景”把技能设计得又大又杂比如“财务分析助手”希望它既能处理报销、又能出具财报、还能做预算预测。实际结果是模型拿着这么大的技能经常在做具体任务时不知道该走哪条流程。我的处理思路是一旦发现技能内部存在三种以上完全不同的操作路径就拆分成多个技能。一个技能最好只代表一条清晰的任务线。如果担心拆分后技能数量太多可以通过描述里的“相关技能推荐”来补充指引模型在必要时串联使用。6.2 坑二对模型的指令遵循能力过度自信第二个坑是相信模型一定能被一段强势的prompt完全约束住。实测中模型经常在复杂上下文里“忘记”部分指令尤其是那些写在技能文档中部的约束条件。与其反复用文字强调不如把关键约束抽象成强制校验逻辑在代码侧拦截而不是指望模型自觉。比如“删除类操作必须二次确认”这个约束技能描述里可以写但更重要的是在函数入口判断参数中是否包含confirmtrue没有就直接拒绝执行并提示用户确认。把安全边界放在代码层比放在prompt层可靠得多。这是我反复验证后得出的结论也是我建议所有做agent的团队优先落实的原则。6.3 坑三缺乏对技能效果的“离线评估”第三个坑是只做在线效果观察不做离线评估。线上metrics有延迟、有噪声而且用户行为本身会影响结果归因很难快速判断一次技能改动是变好还是变坏。我现在的做法是建一个离线评估集里面包含来自真实场景的几百条任务样本每一条都标注了理想技能路径和关键输出特征。每次改技能后先离线跑一遍评估集看技能选择正确率和关键步骤完成度是否下降。如果离线不过关就不上生产。这套流程看起来笨但是在上线前过滤掉了很多肉眼看不出来的退化问题。6.4 坑四把技能名的“相似性”当成了可复用性第四个坑是关于技能命名和复用的。最开始做技能库时我自己也犯过“同名不同义”的错比如“生成报告”和“数据分析报告”两个技能名字相似内部逻辑也部分重叠但输出格式不同。模型在调用时经常选错给用户带来困惑。后来我规定技能命名必须唯一且名字要能直接体现任务差异。“生成报告”改成“生成PPT版项目周报”“数据分析报告”改成“生成CSV版用户行为分析报告”两者从名称上就能区分。同时给这两个技能的description里都加上互相排除的提示“若用户需要PPT格式使用前者若需要CSV数据文件使用后者。”这样技能库的使用体验提升非常明显。7. 从技能库到组织能力版本管理、经验沉淀和边界意识7.1 技能也应该有版本管理和评审机制技能不是写一次就完事的静态资产它会随业务逻辑和数据口径不断变化。我建议把技能当代码库管理纳入git版本控制每个技能都有独立的变更记录。修改时必须带上更新说明比如“调整了指标口径”“增加了某个参数”“修正了错误示例”。有条件的话最好建立一个“技能评审”机制参照代码review的流程。每次技能变更至少找一个熟悉业务、一个熟悉技术的人过一遍。业务视角看描述是否准确技术视角看参数和契约是否合理。单人维护的技能库到后期一定会出现描述和实际行为不一致的情况。7.2 把“踩坑教训”随技能一起沉淀技能文档里的边界与兜底字段除了写“怎么做”建议也写“踩过哪些坑”。比如“本技能不适用于退款场景退款场景请使用售后技能因为两套系统的订单状态不同步”。这类经验是调试agent时最宝贵的信息也是团队知识积累的核心载体。我维护的技能库里有好几条类似备注是经过线上故障才沉淀下来的。每次故障结束后我们都会反思这是不是技能文档缺失导致的如果是立刻补充。长期坚持下来技能库会逐渐变成团队的“活知识库”而不只是一堆函数签名。7.3 时刻保持“模型只是执行者”的边界意识最后说一个比较抽象但重要的体会。无论技能怎么设计模型始终是一个概率推理系统它可能在极端情况下做不可控的事情。我们要做的是通过技能和代码把不确定性收敛到可接受的范围而不是期待模型永远正确。凡是涉及资金操作、权限变更、敏感信息传输的动作技能层一定要有硬性校验机制。技能文档里写清楚“做什么”代码逻辑里把“绝对不能做什么”堵死。这两者一个管能力一个管边界缺一不可。写在最后的实操心得整套agent-skills体系我是在做了两三个真实项目之后才逐渐建立起来的方法论。现在回头看最早的版本失败不是模型选型的问题也不是框架不行而恰恰是技能设计粗糙导致的——功能的边界模糊描述信息量不足也没有任何测试和沉淀机制。如果让我给刚开始做agent的朋友一句建议我会说先花两周时间把技能库当成产品来设计比盲目堆功能有价值得多。另外还有一个小工具层面的经验。现在很多主流agent框架都支持skills的定义但各自的字段和能力边界不相同。不要为了省事把一个框架的技能定义逻辑照搬过来换框架时建议重新梳理一遍技能的粒度、描述和校验逻辑。技能是agent的心脏移植心脏时多花的时间一定会在后续运行里成倍赚回来。