agent-skills实战：大模型技能库设计与落地避坑指南

做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混在一起说，其实它们的边界并不一样。虽然不同框架对这几个词的叫法有差异，但在落地层面我们是能理清的。

在我的实践中，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.py

SKILL.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技能再注入。

我现在的项目用的是动态注册加向量检索混合：高频常用技能全量注入，低频长尾技能走检索。这样既保证了核心体验，又控制了上下文长度。技能接入后我还做得一件事是日志记录：每一次技能选择的结果、模型是选了还是没选、选的是哪个技能，全部落日志。没有日志，后面排查问题全靠猜。

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没有一步到位的完美方案，我的经验是从最小场景开始，一个技能一个技能地打磨描述、参数和执行逻辑，跑通一个再加一个。技能库的质量，最终取决于你对业务细节的理解深度，而不是模型本身的能力大小。