★ FEATURED ARTICLE 做agent项目最怕什么我经历过几次从demo到落地的完整循环之后最大的体会是agent-skills这块没想明白项目基本就卡在“能聊不能干”的阶段。很多团队把模型接进系统发现它除了会对话什么实际动作都做不了就是因为缺了技能层——也就是让大模型真正“动手”的那套可调用能力。agent-skills本质上解决的是大模型的能力边界问题。它把“模型知道怎么做”变成“模型真的能做出来”通过定义清晰的技能接口、参数契约、执行逻辑和反馈格式让模型在合适的时机调用合适的能力完成真实业务动作。这篇文章我会直接结合我实操过的技能库搭建过程把设计思路、落地步骤和踩过的坑一次讲清楚适合正在做智能体应用、或者准备让agent接入业务流程的团队参考。1. agent-skills到底是什么一次说清概念与边界1.1 从大模型“会聊”到“会做”skills的价值核心大模型本身只是一个文本生成器。你问它问题它给你回复但这个回复只是文字。真正要让agent完成“查一下订单状态”“给客户发一封跟进邮件”“把这份表格里的数据整理成报表”这类动作光靠文本输出是远远不够的。你需要让模型能够调用外部系统、执行代码、操作数据这就引出了agent-skills。我习惯把skills理解成“给大模型装上的手”。模型的大脑负责决策——判断用户想干嘛、当前场景需要什么能力、应该选哪个技能而技能库负责执行——真正去调用API、读写数据、触发工作流然后把执行结果返回给模型。大脑和手之间的配合靠的就是一套标准化的技能定义。如果一个agent项目里skills层做得散乱模型就会频繁选择错误、参数传错、或者根本不知道该用哪个能力整个系统就会变得不可控。技能的另一个价值是复用。不同业务场景里有大量重复操作比如“格式化时间”“查询用户信息”“发送通知”。如果每个agent都各自实现一遍代码会冗余维护成本也很高。把通用操作沉淀成标准skill然后所有agent统一引用这才是技能库该有的姿态。1.2 skills、tools、plugins、workflows别被术语绕晕我在和同行交流时发现很多人会把skills、tools、plugins、workflows混在一起说其实它们的边界并不一样。虽然不同框架对这几个词的叫法有差异但在落地层面我们是能理清的。术语核心定位典型例子关键点tools底层可调用函数/接口查询天气API、发送HTTP请求偏基础没有业务语义skills带语义、带约束的能力封装根据城市名查询实时天气并生成出行建议包含触发条件、参数契约、执行逻辑plugins第三方扩展模块浏览器插件、代码解释器插件通常是现成生态拿来即用workflows多步骤流程编排从客户投诉到生成工单再到自动回复关注流程状态和节点跳转在我的实践中skills和tools最容易被混淆。工具是单纯“能做某个动作”技能则是“知道什么时候该做这个动作、怎么做才符合业务规则”。举个例子一个send_email工具只要把邮件发出去就算完成但一个send_followup_email技能会先判断用户最近是否有未回复的会话、检查邮件内容是否符合话术模板、确认收件人是否在可联系名单里这些判断逻辑都封装在技能内部。这种封装的直接好处是让模型侧的定义变得简洁。你不需要在提示词里写一大堆业务规则只需要告诉模型“这个技能用于什么场景、什么时候调用、需要哪些参数”剩下的交给技能内部处理。这也是为什么我建议团队把重业务逻辑尽量下沉到skill层而不是堆在prompt里。2. 为什么agent-skills难做拆解核心设计思路2.1 技能不是功能清单而是“可编程的行为单元”很多人设计技能库时第一个动作就是拉一张API清单把内部系统所有接口都列出来然后逐个塞进agent。这样做出来的东西不是技能库是灾难现场。模型面对几十个细节重叠、命名混乱的接口大概率会选错、调用错、甚至直接放弃调用。技能应该被当作“行为单元”来设计。一个行为单元包含五个要素输入、动作、输出、前置条件、副作用。输入是模型需要提取的参数动作是技能内部执行的逻辑输出是返回给模型的规范化结果前置条件规定了哪些情况下才能调用比如用户必须已登录、订单必须存在副作用则明确这个技能会不会产生外部影响比如是否真发了一封邮件、是否真的扣了钱。举例来说我做过一个客服场景的技能库里面有一个叫refund_order的技能。技能定义里明确写了前置条件订单状态必须是“已支付”且未超过退款期限副作用会发起退款流程并发送通知输入参数只需要order_id和reason。模型只要拿到这两项就能调用至于退款到账时间、审批流程、通知文案全部封装在技能内部。这样设计的好处是模型推理负担小而且业务规则不会在对话中泄露或出错。2.2 设计技能时最常见的三个误区第一个误区是技能描述写得像开发文档。很多团队直接把API文档里的说明贴在技能定义里比如“该方法用于根据指定标识获取对应用户详情参数包括用户唯一标识符”。这种语言太技术化模型理解起来很费劲。我更推荐写成“用户想知道某个具体用户的信息时使用例如查看资料、核对身份参数id是用户的唯一编号”。模型擅长理解意图和场景而不是函数签名。第二个误区是技能粒度太粗一个技能做太多事。我以前把一个“处理客户请求”的技能写得包罗万象既能查信息、又能发通知、还能改状态。结果模型经常不知道它到底该干什么参数也不知道怎么填。后来拆分成lookup_customer、update_customer_status、send_notification三个技能准确率立刻上去了。技能越单一模型的选择越清晰。第三个误区是只考虑成功路径不考虑失败和撤回。真实世界里API会超时、数据会缺失、用户会撤回操作。如果技能没有定义失败时的返回格式和处理动作模型只能瞎猜或者用一段含糊的话糊弄用户。我现在每个技能都必须定义清晰的错误码、错误信息和可恢复动作比如“订单不存在”时建议模型给出进一步引导。2.3 技能粒度怎么定粗与细的取舍技能粒度没有标准答案但有几个判断维度可以参考调用频率、业务复杂度和安全风险。高频且单一的操作应该是最细的一个技能比如“查询余额”低频但流程固定的操作可以稍微粗一点比如“创建带审批的请假申请”安全敏感的操作必须独立成技能方便做二次校验和审计不能跟其他逻辑混在一起。另外还要考虑上下文长度。每个技能的定义都会占用模型上下文如果技能库有几十个技能系统提示词就变得很长模型注意力会被稀释。所以我在设计技能时尽量让单个技能的描述控制在100到200个中文字符以内详细规则放到技能内部文档里而不是全部塞给模型看。真正好的技能设计是让模型“知道存在这个能力、知道什么时候用”而不需要让模型了解内部实现细节。3. 从零落地一个技能库实操步骤与关键细节3.1 技能目录与命名规范我搭技能库的第一步不是写代码而是定目录结构。合理的目录能让技能检索、维护、扩展都变得顺畅。目前我用得比较顺手的一套结构是这样的skills/ domain/ customer/ lookup_customer/ SKILL.md schema.json run.py tests/ test_basic.py test_errors.py refund_order/ SKILL.md schema.json run.py common/ format_datetime/ SKILL.md schema.json run.pySKILL.md是给人看、也给模型看的核心描述文件schema.json是参数与输出契约run.py是执行逻辑tests下面是回归测试。按业务域拆分的核心逻辑是让同领域的技能尽量聚在一起这样后续做权限管理和监控都比较方便。命名规范我一直坚持三个原则短、动词开头、无歧义。lookup_customer比get_customer_data_by_id清晰refund_order比process_payment_refund_request容易理解。模型对动词开头的命名更敏感调用准确率会更高。另外同一个领域的技能前缀要统一比如招商银行类技能统一叫cmb_*这样即使技能多了也不会乱。3.2 技能描述与参数契约怎么写SKILL.md是整个技能库的灵魂。模型能不能正确判断触发时机90%取决于这个文件写得好不好。我现在写SKILL.md有一套固定模板每个技能都按这个模板来避免各写各的。# lookup_customer ## 用途 帮助用户查询客户的基本信息例如姓名、联系方式、会员等级、最近订单时间。 ## 触发条件 - 用户询问某个客户的资料 - 用户需要核对客户身份 - 用户提到客户编号并想了解情况 ## 不要使用的情况 - 用户想修改客户信息请使用 update_customer - 用户想查询订单详情请使用 lookup_order ## 参数 - customer_id: 必填字符串客户的唯一编号格式如 C123456可在对话中提取。 - include_contact: 选填布尔值是否返回联系方式默认 false。 ## 返回 成功返回客户信息 JSON失败返回错误码格式见 schema.json。 ## 副作用 无。本技能只读数据不修改任何内容。写触发条件的时候我特别注意一个问题要写哪些情况应该用更要写哪些情况不该用。很多技能被模型误调用就是因为没有写清楚边界。比如lookup_customer的描述如果不写“不要用于修改客户信息”碰到“帮我把这个客户的电话改一下”的请求模型可能也去查一遍客户完全没有意义。参数契约我习惯用schema.json单独定义而不是写在SKILL.md里。原因是参数多了以后文本描述容易遗漏或者产生歧义。JSON Schema对类型、必填、枚举、示例都有严格约束模型侧即使不读完整Schema也能通过系统提示词自动映射到function calling的标准格式。{ type: object, properties: { customer_id: { type: string, description: 客户的唯一编号格式如 C123456, examples: [C123456] }, include_contact: { type: boolean, description: 是否返回联系方式, default: false } }, required: [customer_id] }3.3 参数校验与错误处理别把脏数据送进下游模型生成的参数经常不靠谱。它会生成一个不存在的customer_id会把电话号码塞进邮箱字段还会漏掉必填参数。所以技能execution层的第一道关卡就是参数校验绝对不能把模型给的原始参数直接透传给下游API。我通常会先做三层校验类型校验、格式校验、业务校验。类型校验就是确认传进来的是字符串、整数还是布尔值格式校验检查正则匹配比如订单号前缀、日期格式业务校验最花时间需要读取数据确认实体存在、状态合法。前两层可以用现成的schema校验库快速完成第三层需要在执行逻辑里写判断。# run.py 片段 from skills.common.validators import validate_schema def run(context, params): errors validate_schema(params, schema_json) if errors: return {error: PARAM_INVALID, detail: errors} customer_id params[customer_id] # 业务校验确认客户存在 customer db.lookup_customer(customer_id) if not customer: return {error: CUSTOMER_NOT_FOUND, detail: f客户 {customer_id} 不存在} return {data: customer.to_dict()}错误返回的格式我固定成{error: 错误码, detail: 描述}。为什么不用纯文本因为模型看到结构化错误码之后能够更稳定地做出下一步判断比如CUSTOMER_NOT_FOUND时它可以告诉用户“这个客户我没找到请确认编号”而不是重新编一个解释。错误码也会方便我们后续做监控分析看看哪些错误反复出现从而反向优化技能定义。3.4 技能测试与回归没测试的技能别上线我见过太多技能上线前只在测试环境点了一次然后生产环境翻车。技能测试要覆盖的不只是正常路径还有边界输入、错误路径和模型层的调用路径。我一般会为每个技能写一组测试用例模拟模型可能传的各种参数组合。核心是一套模拟调用器——不是直接调run函数而是模拟大模型输出的JSON格式参数走完整的校验和执行链路。这样能提前发现参数schema和代码逻辑之间的脱节。# tests/test_lookup_customer.py def test_normal_lookup(): result invoke_skill(lookup_customer, {customer_id: C123456}) assert result[data][name] 张三 def test_missing_param(): result invoke_skill(lookup_customer, {}) assert result[error] PARAM_INVALID def test_nonexistent_customer(): result invoke_skill(lookup_customer, {customer_id: C999999}) assert result[error] CUSTOMER_NOT_FOUND每次修改SKILL.md或run.py之后除了跑这些单元测试我还会跑一轮“意图回归测试”准备一批真实或模拟的对话数据让agent完整地走一遍统计技能选择正确率、参数完整率和最终任务成功率。意图回归测试的成本高但价值巨大。它的作用不只是验证技能本身更是验证描述文本改动会不会让模型在边界情况下选错技能。3.5 模型侧如何发现技能注册、注入与检索技能库搭好之后还有一个关键步骤怎么让大模型知道这些技能。目前主流做法有三种全量注入function calling、动态注册、向量检索。全量注入就是把所有技能都以function calling定义的方式放进系统提示词。这个方法简单但技能数量超过20个以后上下文变长、注意力分散效果明显下降。动态注册会先根据用户对话内容判断可能的技能类别然后只注入相关的几个技能定义。向量检索则是把技能描述embedding化对话进来时用相似度检索top-k技能再注入。方式适用规模优点缺点全量注入技能数少20实现简单上下文长、选择准确率下降动态注册技能数中等按需注入、性能好需要分类逻辑向量检索技能数大扩展性好依赖embedding质量、检索有误差我现在的项目用的是动态注册加向量检索混合高频常用技能全量注入低频长尾技能走检索。这样既保证了核心体验又控制了上下文长度。技能接入后我还做得一件事是日志记录每一次技能选择的结果、模型是选了还是没选、选的是哪个技能全部落日志。没有日志后面排查问题全靠猜。4. 常见问题与排查技巧实录4.1 技能描述写得很好但模型就是不调用这是团队群里问得最多的问题。描述明明写得很清楚但模型在“查一下张三的余额”这种请求下就是不调用查询技能而是用聊天知识库胡编一个数字。我排查这类问题的第一步是看模型实际生成的工具调用日志。大多数框架都会记录模型是否生成了tool_call如果没有生成那问题多半出在技能发现环节技能没有被注入到上下文或者描述里的触发条件不够贴近用户口语。一个非常有效的技巧是把用户说过的真实句子直接写进SKILL.md的触发条件里而不是写那些抽象的业务术语。比如不要写“当用户需要查询账户资产信息时”要写“当用户说‘查一下余额’‘我还有多少钱’‘我的账户里有多少’时”。有了这些真实的表达模板模型的匹配能力会大幅提升。触发条件里的用户说法越具体模型越容易对齐。4.2 参数解析错误与类型不匹配模型的“手滑”怎么防模型在生成参数时经常会把“五月一号”解析成字符串而不是日期对象会把“高一点”这种模糊描述直接塞进数字字段。这类问题在技能层靠严格校验只能把错误挡出去但不能解决“模型不知道该填什么”的根因。我建议在参数schema里增加更强的提示示例。比如amount字段除了写类型还可以写examples: [100, 350.5]并且描述里说明“如果用户说的是模糊表达比如‘多一点’‘随便’不要填写先与用户确认”。有时候模型没有生成任何tool_call其实是因为它不知道如何填参数而放弃了调用。这时候与其让它瞎猜不如让它主动反问用户。这个逻辑我会写进SKILL.md里参数不全或不确定时先向用户确认不要继续执行。另外在代码层做宽容解析也很重要。比如日期字段用户可能写“明天”、“下周一”、“2025-5-1”最好统一做一个日期解析器能转就转转不了再报错。这些容错处理能显著提升技能的真实可用率。4.3 并发、超时与状态管理当多个用户同时在用agent时技能执行就不是单个函数调用那么简单了。我踩过的坑是技能内部用了全局缓存结果A用户的数据被B用户看到。现在我每个技能执行都强制使用独立的上下文对象所有临时状态都放在这个对象里绝不跨会话共享。超时处理同样容易翻车。有些技能调用下游API可能要10秒而模型侧通常会等待工具调用返回等待太久会报错。我的方案是技能执行分同步和异步两类耗时小于3秒的走同步调用直接返回结果耗时较长的技能先返回一个任务ID再通过check_task_status技能让agent轮询状态。这个设计虽然多了一个技能但避免了大量超时异常。如果你用的是异步方案一定要记得在技能描述里写明“本技能执行时间较长调用后请通过查任务状态接口确认结果”。否则模型可能以为同步返回直接给用户说“已完成”实际上任务还在跑。4.4 技能冲突与命名空间技能一多冲突问题就会出现。最典型的是两个技能都能处理同一个查询但业务规则完全不同。比如我做过一个系统里面有lookup_order_status和lookup_refund_status用户说“我的退款到哪一步了”时模型有时会去查订单状态技能拿到的结果完全不对。这种问题我建议从三个层面解决第一在SKILL.md的“不要使用的情况”里明确写清边界第二给技能增加分类前缀比如refund_*和order_*让模型更容易区分第三在同一意图被多个技能覆盖时用技能优先级字段调度框架优先选择高优先级技能。还有一种隐藏很深的冲突是技能之间的依赖循环。比如技能A内部调了技能B技能B又调用了技能A一旦触发就会死循环。我现在的做法是技能内部只允许直接调用domain函数或API不允许技能之间任意互相调用。跨技能调用必须通过agent层的编排逻辑这样循环依赖在编译期就能被发现。4.5 安全边界风险操作一定要二次确认技能库里最难处理的是带副作用的敏感技能。比如发送营销邮件、修改订单价格、执行退款虽然用户或模型说得很自然但绝对不能无脑执行。大模型本身不具备安全判断能力它可能因为prompt注入被诱导去调用危险技能。我在每个敏感技能的设计里都强加了确认机制agent在执行前先通过另一个技能confirm_action向用户展示“即将执行的操作内容和影响”用户确认后才真正执行。这个确认动作本身也被定义成一个技能模型必须调用它才能继续。这样一来即使模型被诱导也会在确认环节被拦下来。另外一个安全习惯是权限最小化技能的执行账号不要用超级管理员权限每个技能只开通完成自身任务所需的最小API权限。比如lookup_customer只给只读权限refund_order只给退款接口权限。这样即使某个技能被恶意调用影响范围也能被控制住。最后分享一个我一直在用的小技巧给技能库加一个record_observation技能让agent在关键节点记录自己的判断依据和操作原因。它不直接影响业务动作但会让整个技能调用链条变得可复盘。调试的时候这个“记录思维过程”的技能比任何日志打印都好使。agent-skills没有一步到位的完美方案我的经验是从最小场景开始一个技能一个技能地打磨描述、参数和执行逻辑跑通一个再加一个。技能库的质量最终取决于你对业务细节的理解深度而不是模型本身的能力大小。
阅读完成 · 觉得有帮助？
