AI Agent 技能库构建指南：从设计原则到测试落地

1. 先从“技能”两个字说起Agent 为什么需要一套技能库如果你最近也在折腾 AI Agent大概率会有一种感觉模型本身已经很聪明了但让它真正去干活儿的时候总是差点意思。让它查个数据、发个请求、算个东西要么不会调用工具要么调用了又传错参数要么干脆一本正经地编一个结果出来。这时候你会意识到一个关键问题——模型不缺知识缺的是“能力封装”也就是 agent-skills 这个概念要解决的事情。agent-skills翻译成大白话就是“智能体技能库”。它不是某一个具体工具也不是一套现成的代码框架而是一种把 Agent 能做的事情结构化、标准化、可复用化的方法。你可以把大模型当成一个非常聪明但毫无经验的实习生它什么都懂一点但你交给它的每一项具体任务都需要有明确的操作手册、输入输出标准、边界条件和异常处理方案。这整套“操作手册”的集合就是技能库。我最早接触这个概念是在做一个内部效率工具的时候。当时团队里的模型已经接了好几个 API能查库存、能算排期、能发通知但每次新增一个功能都要改一大圈代码而且经常出现模型“乱用工具”的情况。后来我们参考了当时社区里流行的做法把所有可复用的能力拆成独立技能统一注册、统一描述、统一测试效果立竿见影。这篇文章就是想把这一整套实践拆开来讲清楚。这套方法论适合谁正在做 Agent 应用的开发者、想要让大模型落地到具体业务场景的产品经理、还有对 AI 工程化感兴趣的学生和研究者。无论你用的是哪种模型、什么框架技能库的核心思路都是通用的而且越早设计好后面的坑越少。2. 技能库到底在解决什么问题2.1 大模型的“知识”和 Agent 的“能力”是两码事先说个我踩过的坑。刚开始我做 Agent 时以为只要把模型接入几个工具函数它就会像个全能的助手一样干活。结果实测下来完全不是那么回事。为什么因为模型知识是“记忆型”的而任务执行是“操作型”的。打个比方你让一个读过无数菜谱的人去炒菜他理论上知道盐放多少、油温多高但真正上手时他需要知道灶台在哪里、锅铲怎么拿、火候怎么看。这些操作层面的“肌肉记忆”菜谱里不会写知识库里也不会有。Agent 也一样——你给它一个函数叫get_weather它知道这个函数能查天气但它不一定知道什么时候该用这个函数、参数应该怎么传、返回结果应该怎么解读。技能库的核心价值就是把“模型知道什么”和“模型能做什么”之间那条鸿沟填上。每个技能不仅仅是段代码它通常由三部分组成技能描述告诉模型这个技能是干嘛的、什么时候用、调用接口定义输入输出的结构、实现逻辑真正执行任务的代码。这三者缺一不可。2.2 没有技能库的 Agent 项目长什么样为了说明技能库的价值我画个对比场景。假设你要做一个智能客服助手支持查订单、退换货、改地址三个功能。没有技能库的做法是在系统提示词里写“你可以调用查订单、退换货、改地址这三个工具”然后代码里定义三个函数。听起来挺清晰对吧实际跑起来问题一堆用户说“我要退货”模型调用的是查订单工具因为“退货”和“订单”这俩词在语义上太近了模型分不清。用户说“把收货地址改一下”模型知道该用改地址工具但把new_address参数传成了“地址改为”这个完整句子而不是标准化的省份、城市、街道结构。用户的问题稍微复杂点比如“上周买的那个蓝色耳机要退货”模型直接懵了不知道是先查订单还是直接走退货流程。这些问题本质上是技能封装得不够好。技能库要做的就是给每个技能足够清晰的触发条件、参数说明、调用时机以及与其他技能的关系描述。好的技能设计能让模型像一个经过培训的老员工而不是一个看过说明书就上手的临时工。2.3 技能库的另一个隐藏价值复用与评测技能库还有一个容易被忽略的收益——可复用性和可评测性。当能力被拆成一个一个独立技能后你可以在多个 Agent 应用里共享同一套技能。比如查天气这个技能客服助手能用行程规划助手也能用完全不用重新开发。更重要的是技能可以单独测试、单独评估。你可以针对每个技能构造测试用例验证“给定的输入是否触发了正确的技能调用”“参数是否传对了”“返回结果是否被正确解析”。这在传统的单体 Prompt 函数调用方案里是很难做到的因为所有逻辑搅在一起出了问题只能整个流程一起调试。3. 技能目录设计怎么拆技能、怎么定接口3.1 技能粒度拆太粗或太细都会出问题做技能库第一个要决策的事情是技能拆分的粒度。这个粒度直接决定了后续的维护成本和调用准确率。拆得太粗一个技能承担了太多职责。比如搞一个process_order技能里面又是查单、又是改地址、又是退换货。对模型来说这个技能的功能边界太模糊什么时候该调它、调完返回什么都说不清楚。而且一旦某个分支逻辑挂了整个技能都得排查。这跟写代码不拆函数是一个道理短期看着省事长期必出问题。拆得太细同样麻烦。比如查天气一个技能就拆成get_temperature、get_humidity、get_wind三个独立技能。看似精确实则有害因为模型面对的工具列表变长了选择成本急剧上升。你有十个技能的时候模型可能挑得对你有一百个技能的时候模型大概率会在判断“该用哪个”上犯迷糊反而引入更多定位问题的噪音。我自己的经验是以“用户意图”为粒度来拆技能。一个技能应该对应一个相对完整的用户需求边界要清晰职责要单一。举个例子查天气是一个技能参数是地点和日期返回温湿度、天气状况、风力。设提醒是一个技能参数是提醒内容和时间。查汇率是一个技能参数是货币对和日期。有些场景需要“组合”两个以上技能来完成一个复杂需求那就让 Agent 自主编排调用顺序而不是强行封装到一个大技能里。组合可以发生在 Agent 这一层技能库本身保持简洁和单一职责这是比较稳妥的设计原则。3.2 技能描述一小段话决定 Agent 会不会用对技能技能库设计里最容易被轻视、但影响最大的环节是技能描述description怎么写。模型不像人它看不到你的函数体内部逻辑它对一个技能的认知完全来自你给它的描述文本。描述得好不好直接决定了工具调用的准确率。我记得有篇论文里做过一个实验把工具描述从一两句话扩充到包含“什么时候用”“什么时候别用”的详细版本后模型在多工具选择任务上的准确率提升了非常可观的比例。这个结论在我自己的实践里也得到了验证。那怎么才算一段好的技能描述呢我的经验是至少包含以下几个要素功能概述这个技能做什么的一句话说清楚。适用场景什么样的对话/任务应该触发这个技能给一两个典型例子。不适用场景什么样的对话不应该触发尤其是容易混淆的情况。调用注意事项比如某些参数是可选的、某个字段格式有特殊要求等。举个例子。我做过一个日程管理的技能库一开始create_event的描述就一句“创建日历事件”。结果模型经常在用户只是“询问某个时间有没有空”的时候就调用它创建事件造成一堆垃圾日程。后来把描述改成当用户明确表达要新建一个日程/预约/会议时调用。如果用户只是询问某时间是否空闲、或查看已有安排请改用 query_events 技能。创建时需要确认时间、标题、参与者等信息。改完以后误调用的情况基本绝迹了。描述不是写给用户看的是写给模型看的这句话我每次分享都会强调一遍。3.3 接口设计用 JSON Schema 给模型划清边界对模型来说参数结构越清晰、越接近自然语言习惯越不容易出错。目前业界比较通用的做法是用 JSON Schema 来描述每个技能的输入参数。原因是大多数模型在“根据 Schema 生成符合结构的 JSON”这件事上表现相当不错比让它理解自定义格式可靠得多。在定义 Schema 时有几个容易被忽略的细节。一是字段命名尽量语义化比如用destination而不用dst。别以为缩写省 token换来的是大量的传参错误。二是必填字段和可选字段一定要分清楚并且把必填约束写进描述里。三是给字段加上格式示例比如日期写“2026-03-15 14:30”模型照着填比让它自己理解“明天下午”怎么转成日期要靠谱得多。还有一个很实用的技巧是在 Schema 描述里注明字段允许的取值范围和排除值。比如一个查询范围参数取值范围是[all, completed, pending]你直接在描述里写清楚模型就不会发明新值了。4. 实操全流程一个技能从定义到上线4.1 目录结构与基础封装下面我用一个真实的技能来走一遍从零到一的流程。假设我们要给 Agent 做一个“查快递物流”的技能这个技能能接受快递单号和公司名返回最新的物流节点信息。我习惯的项目目录结构长这样skills/ ├── tracking_query/ │ ├── __init__.py │ ├── skill.py │ ├── schema.json │ └── tests/ │ ├── test_skill.py │ └── fixtures/ ├── weather_query/ │ ├── ...每个技能独立一个文件夹里面放实现代码、参数 Schema、测试用例。这样每个技能可以被单独开发、单独维护也好做跨项目复用。技能和技能之间尽量不要互相 import保持解耦否则后期会陷入循环依赖的泥潭。4.2 用代码实现一个技能的核心骨架以查快递为例核心实现可能长这样。这里我直接用最朴素的函数封装不加任何复杂依赖方便理解# skill.py import json from datetime import datetime DISPATCH_QUERY_FUNCS {} def register_skill(name: str, description: str, schema: dict): 注册技能的装饰器。 def decorator(func): DISPATCH_QUERY_FUNCS[name] { name: name, description: description, schema: schema, func: func, } return func return decorator register_skill( nametracking_query, description当用户提供快递单号或询问包裹物流状态时调用。如果快递单号未提供请先向用户索要。, schema{ type: object, properties: { tracking_no: { type: string, description: 快递单号例如 SF123456789 }, company: { type: string, description: 快递公司名称可选默认自动识别, enum: [顺丰, 圆通, 中通, 申通, 韵达] } }, required: [tracking_no] } ) def tracking_query(tracking_no: str, company: str ): # 这一段是实际实现我这里用 mock 数据代替真实调用 result { tracking_no: tracking_no, company: company or 自动识别, status: 运输中, latest_event: 已到达【上海转运中心】, latest_time: datetime.now().isoformat() } return json.dumps(result, ensure_asciiFalse)这个小例子展示了整个技能的核心要素register_skill帮我们把技能注册到一个全局字典里。实际项目中这个字典最终会被 Agent 框架读取作为模型可用的工具列表。description字段直接说明“什么情况下调用”并且特别注明了“信息不全时先问清楚”。schema结构和字段说明写得清晰精确。实际函数内部做的事就是取参、执行、返回 JSON 字符串。这里有个重要细节返回值建议统一用 JSON 字符串。这么做有一个好处就是无论技能的底层实现用的是同步函数、异步请求还是调用外部服务最终的调用方拿到的一定是统一格式的文本方便模型直接读取也方便上层日志记录。我见过不少新手在返回值格式上随心情今天返回 dict明天返回列表后天返回字符串结果 Agent 解析逻辑写得异常痛苦。4.3 让 Agent 真正“学会”调用这个技能技能代码写完了只是第一步。接下来要做的是把注册好的技能挂到你的 Agent 工作流里。以命令式框架为例我一般直接在 Agent 初始化时把技能列表传进去from agent import Agent agent Agent( modelyour-model-name, skillslist(DISPATCH_QUERY_FUNCS.values()) )这样 Agent 在每次对话时系统提示词里会自动带上所有注册技能的名称、描述和 Schema。模型会根据用户输入来决定调用哪个技能、传什么参数。如果你用的是更偏代码编排的框架技能层往往表现为可被agent.run()直接调用的工具。核心逻辑不变模型先读所有技能描述再生成结构化调用指令框架解析指令、执行对应函数、把结果回传给模型继续生成回复。这一步看起来简单但实际操作中有很多细节会坑你。比如技能数量一旦超过十个模型的选择准确率会明显下降。我在项目里第一次挂了十五个技能时模型就开始频繁选错工具。后来我做了两件事一是精简了一些逻辑回归到更粗粒度的技能上二是给容易混淆的技能都写清了“何时不用我”准确率才回到比较理想的水准。4.4 测试先行给技能做单元测试与回归测试技能上线前一定要写测试这点怎么强调都不过分。技能是 Agent 的核心执行单元一旦技能返回了错误结果模型再聪明也会在错误的基础上编造出更离谱的答案。我自己遇到过最典型的案例就是查快递的技能因为快递公司参数映射错误把“圆通”的物流返回成了“中通”的数据模型还一本正经地跟用户说“您的包裹已由中通揽收”。这种错误最难排查因为它不是模型的问题是底层技能的问题。因此在正式接入 Agent 之前我至少会给每个技能写三类测试第一类是正常调用测试构造典型参数验证返回结果结构是否正确。第二类是边界输入测试比如传入空字符串、非法参数、缺失字段等确保代码不会抛异常而是返回一个语义明确的错误信息。第三类是描述准确性回归测试我会在每次修改技能描述后用一小组真实用户问题跑一遍“模型是否会正确触发该技能及生成参数”。第三类测试很多团队不做但我觉得是性价比最高的一个环节。你可以准备一组标注好的测试问题集例如用户提问期望触发的技能期望参数“帮我查下今天到北京的航班”flight_query{destination: 北京, date: 今天}“圆通快递单号YT123456789到哪了”tracking_query{tracking_no: YT123456789, company: 圆通}“明天上海天气怎么样”weather_query{city: 上海, date: 明天}每次改技能的描述、参数结构或实现逻辑就全量跑一遍这些用例能及时发现“改了 A 技能结果 B 技能的触发率下降了”这类隐藏回归。这类问题在 Agent 应用里非常隐蔽依赖人工探索基本发现不了一定要靠用例集自动回归。5. 常见问题与排查技巧实录5.1 模型死活不调用技能怎么办这是所有 Agent 开发者都会遇到的第一个问题。你注册好了技能描述也写了示例也给了但模型在应对用户需求时就是不调用反而直接靠自己的“记忆”编答案。排查思路我一般按顺序走先确认技能是否真的被框架注入到了上下文中。很多刚上手的朋友在配置里写错了技能路径或者注册函数没有执行结果模型根本不知道有这些技能存在。这个检查起来最简单直接打印agent.available_skills()看看列表里有没有。再检查技能描述是否跟用户问题在表达上“对不上”。模型判断“要不要调用技能”本质上是在做语义匹配如果你的技能描述里写的全是“用于查询物流信息”而用户的表达是“我的包裹到哪了”模型的匹配难度就高了。这种时候把描述改成包含用户常见说法的版本能显著提升触发率。还有一个容易被忽略的原因是模型对不确定信息的处理策略。如果你技能要求必填参数但用户没给全有些模型会倾向于不调用技能直接回复“请提供单号”。这个行为有时是合理的有时则浪费了一次交互。一种绕过的办法是允许技能在参数不全时先调用、内部返回“参数缺失”状态触发追问流程另一种是接受默认值在描述里写明“公司名可选不传时自动识别”。两种方案都试过后者对话体验更顺滑。5.2 参数传对了但执行结果一塌糊涂技能被触发了参数结构看着也正确但执行结果就是不对。这时候先把锅甩给你自己的实现代码别赖模型。最常见的情况是参数值域没对齐。举个例子你的 Schema 里定义公司名枚举是[圆通, 中通, 申通]但内部实现里实际上只处理了[yuantong, zhongtong, shentong]。模型传了“圆通”代码查不到任何对应关系返回 null。这种低级错误在跨团队协作时特别容易发生——定义 Schema 的人和写实现代码的人不是同一个两边各写各的接口就对不齐了。为了避免这类问题我会在技能代码内部加一个参数归一化的前置处理层。所有从模型侧进来的参数必须经过一个转换/校验函数统一成实现内部使用的标准值域。不合法值直接返回明确的报错信息而不要继续往深处传。另外技能返回的结果模型“看不懂”也是一个高频问题。有时候你返回的是一个结构非常复杂的嵌套 JSON模型要找的信息埋在三层以下。这时候模型就容易开始瞎编。解决方式是让技能返回的内容尽量是“人类可读的自然语言化 JSON”——顶层字段放了什么结果直接用平铺结构该拼句子的拼句子。复杂数据不要一股脑丢给模型而是在技能内部完成聚合整理输出一个简洁的结果摘要。5.3 技能数量多了之后准确率断崖式下跌这个现象我做第一个规模化的技能库时也撞上了。技能从八个增加到十五个的时候整体工具选择准确率从很高的水平掉到了不满意的状态。当时第一反应是模型不行后来仔细分析发现问题出在技能之间出现了边界重叠。排查方法也很直接把技能列表打印出来看哪些技能的描述在“功能概述”上有重叠。比如我同时有query_order查订单信息和query_after_sale查售后进度描述都提到了“用户询问订单状态”。模型拿到这种重叠描述自然会抓瞎。处理策略有三板斧一是明确技能之间的分工在描述里主动声明“查询订单请用另一个技能”二是考虑合并同类项如果两个技能都是查状态合并成一个内部加type参数区分模型的选择负担更小三是用技能分组机制把技能按类目划分比如先用路由 Agent 判断用户意图属于“订单类”“售后类”还是“天气类”再在对应类目下选择具体技能。这种分层设计在技能数量较多的场景下非常管用实测准确率提升明显。6. 我的技能库维护心得与扩展建议从第一个技能规模扩展到现在的上百个技能中间经历了不少迷茫期。有些总结是踩坑换来的在这里一并分享出来希望能帮你少走弯路。技能描述每隔两三个月要全面 review 一次。原因很简单模型会迭代你的业务场景也会变。同一个技能在上一版模型上触发得很好到了新版本上就失灵了这种例子我见了太多次。把技能描述当成产品文案来运营定期按真实对话数据去校对比写新技能还重要。技能库一定要有版本管理。技能一旦上线就要定版本号。改描述、改 Schema、改实现逻辑都不能只有一份“当前版本”。我自己的做法是每个技能目录里放一个CHANGELOG.md记录每次变更原因和影响范围。这样出现线上异常时能快速定位到是哪次改动引入的问题。技能的构建过程不是一次性的要跟真实数据持续回流。你现在设计的技能一定会有遗漏一定会有模型误判一定会有用户奇葩需求超过你所有技能的范围。所以一定要在 Agent 系统里留下“技能未命中”的日志。每周翻一遍这些日志收集那些模型想干但找不到对应技能的请求再在下个迭代周期里补上新技能或者调整描述。这是技能库从“能用”走向“好用”最关键的一步。顺便提一个我很想推荐给你尝试的设计技巧给高频技能写“双版本描述”。一个长版本出现在系统提示词的完整技能列表里一个短版本在每轮对话的动态上下文里快速呈现。长版本保证信息完整短版本降低上下文噪音。我在延迟优化和 token 成本控制上这一招效果非常立竿见影。最后说一句可能有点反常识的体会技能库的很多麻烦本质上都不是技术问题而是“设计偷懒”问题。你多花三十分钟把描述写清楚、把边界划明白、把测试跑齐全后续会省下一周的时间去应付那些“模型怎么又乱来”的灵异现象。Agent 的智商上限由模型决定但它的可靠下限完全由你的技能库打磨程度决定。