做LLM Agent开发的人，大概都经历过这种尴尬：模型推理能力上来了，Agent却卡在工具调用这一层，一堆if/else拼起来的调度逻辑，改一个参数就要担心连环炸。前阵子做的这个agent-skills项目，就是为了把技能管理这件事彻底理清楚。你可以把它理解成一个给智能体用的“工具技能库”——以标准Schema注册技能、动态加载工具、统一编排调用链，换模型平台不需要重写工具层，排查问题也不用再靠肉眼盯日志。这篇文章我会从需求拆解讲到核心实现，再把实际跑通项目时踩过的坑一起倒出来，适合已经能写出简单Agent、但想把工具调用做得更工程化的开发者参考。
1. 这个项目要解决的痛点，以及我的动机
1.1 工具调用的工程化困局
先说我的实际感受：Agent应用的开发进度，前期往往被模型选型和提示词设计占据，但真正到了要稳定上线的时候，瓶颈几乎全部集中在“技能层”。我遇到过几个特别典型的场景。
第一是技能定义散落一团。数据库操作、外部接口、本地脚本各自散在不同文件里，Agent需要通过工具调用去触达它们时，只能靠一份随时过期的接口清单。某个查询逻辑改了入参，提示词和调用代码没同步更新，Agent就会反复用旧参数试错。第二是Schema格式不统一。不同大模型平台的Function Calling参数格式存在明显差异，A平台用的是数组结构，B平台可能要求对象再套一层描述。每次切换底层模型，工具层就要跟着改一遍，成本非常高。
第三也是最容易被忽略的问题：技能不可复用。同一个“发送邮件”功能，在项目甲里写了一遍，换到项目乙又复制一份改改。哪天邮件服务的认证方式变了，你得同时去改三个地方。第四是可观测性几乎为零。Agent到底调用了哪个技能、传了什么参数、返回值是什么、这一步消耗了多少token，没有统一打点的话，出了问题根本无从复盘。
agent-skills的出发点，就是把技能当作一等公民来管理。核心不再是“让模型直接调用一堆零散函数”，而是先为每个技能建立一份标准化的身份档案——名称、描述、入参Schema、执行函数、可缓存性、超时策略、权限标签。所有技能进入注册中心，由统一的执行器调度，这样Agent团队只需要关心业务技能的编写，不用每次重复处理格式转换、参数校验、日志埋点这些基础设施。
1.2 为什么不自研工具链，也不用现成框架
有人可能会问：市面上做Agent的开源框架不少，为什么还要自己做一套技能编排？我的判断依据是：通用框架擅长解决“能不能调用工具”的问题，但解决不了“工具规模变大之后怎么组织”的问题。
我当时先用某个主流Agent框架做原型，验证了最基本的工具调用流程。但到了第二个星期，需要接入十几个外部系统时，痛点就很明显了：框架里的工具只是简单的函数列表，缺少技能分组、权限隔离、缓存注解、幂等等概念。团队里某位开发者在注册工具时看漏了参数说明，测试直接把生产环境的库存改乱了。这类事故跟模型能力无关，纯粹是工具管理层缺少约束。
另一个原因是我需要一套能同时兼容多个模型平台的适配层。与其等框架补全多平台格式转换，不如自己在技能注册层就统一成内部Schema，再做一层薄薄的适配器。这样上游业务代码不感知底层使用的具体LLM平台，以后想换更强的新模型，技能收录完全不用动。
需要说清楚边界：agent-skills不是要去重造一个Agent框架。规划决策、上下文管理、提示词模板这些能力，该用框架的继续用框架。这套方案专注的，是从“技能声明”到“技能执行”之间的那段管道，把每个环节标准化。
1.3 适合什么场景，不适合什么场景
这套方案的优势要发挥出来，需要一定的前提条件，我在做技术选型的时候也让团队对照过。
适合的场景是：技能数量在几十个以上，并且持续增长；Agent承担的流程涉及多步调用，经常需要把一个技能的输出喂给另一个技能；项目需要同时对接两个或以上的不同模型平台；团队里有人专门负责技能质量，而不是所有技能都临时在对话代码里“攒”出来。
不太适合的场景也需要坦白讲。如果你只是在做一个演示性质的小型AI助手，总共只有三五个固定工具，用最简单的手写调用即可，引入注册中心反而增加理解成本。另一种情况是业务流程本身极其单一——每天就是调同一个接口返回结果，不需要模型去理解和选择工具。这种情况下做技能编排属于过度设计，先把交互跑通更重要。
2. 整体设计与核心架构拆解
2.1 技能的最小单元是什么
我在设计agent-skills的第一个模型时，用的类比是“菜谱”。菜谱要有菜名、适合什么场合、原料清单和做法步骤，一份技能定义也遵循类似结构。
一个技能由六部分组成：name是唯一标识，模型不会直接看到这个字段的底层变量，但日志和监控会依赖它；description是给LLM看的索引，应当写清楚“这个技能在什么情况下使用”而不是简单一句话带过；schema定义入参结构，字段类型、必填项、取值范围、字段说明都放这里；fn是实际执行函数，只负责完成业务动作，不关心调用它的模型是谁；元信息部分注明tags、cacheable、timeout_ms、requires_auth；最后是version，技能逻辑升级时保留旧版本，线上可以灰度切流。
这种设计最大的好处在于，模型“理解技能”和“执行技能”彻底分离。模型理解技能只依赖description和schema，而真正干活的是fn。因此，我可以随时优化技能描述、调整参数格式，只要Schema版本兼容，Agent的决策层无需同步改动。
2.2 注册中心的目录结构与动态加载
技能注册我采用了目录扫描机制，而不是聚在一个文件里手工注册。项目启动时，注册中心会递归扫描skills/目录下所有__init__.py声明的模块，装饰器负责把每个技能登记到全局注册表中。
我踩过手工注册的坑。技能一旦变多，手动在注册文件里加一行代码特别容易漏；另一层风险是模块循环依赖，A挂了B的装饰器，B又引用A，启动就崩。自动扫描配合装饰器之后，新技能只要放在约定目录下就会自动出现在Agent候选列表里，新人上手也直观。
目录结构大致是：
agent-skills/ ├── registry.py ├── executor.py ├── adapter/ │ ├── platform_a.py │ └── platform_b.py └── skills/ ├── __init__.py ├── email/ │ ├── __init__.py │ ├── send_mail.py │ └── list_inboxes.py ├── metrics/ │ ├── __init__.py │ ├── query_daily.py │ └── export_report.py └── database/ ├── __init__.py └── safe_query.py每个技能子目录里的__init__.py不写逻辑代码，只负责import本目录下的技能模块。注册中心扫描时，通过约定避免加载到废弃文件夹。某个团队以前留了个skills/backup/目录，没加排除规则，结果模型总能用到一个“不存在”的旧技能，排查了很久才发现是扫描器把备份模块也加载进去了。
2.3 技能描述对上下文窗口的影响
每轮对话，LLM平台都会索要可用工具列表。这里有个现实约束：上下文窗口不是无限的，模型能同时感知的技能数量也是有限的。
所以在agent-skills里，技能不是一股脑全量注入的，而是有一个“技能检索+分组裁剪”的流程。我给每个技能打上多个维度的标签，比如email、read_only、analytics。每次构造工具列表时，执行器先根据用户当前意图做一次粗筛，再把命中的技能按优先级排序，最多只暴露前20个。剩下的技能不是不能用，而是放在“二级列表”里，模型可以先调用一个skill_search技能去搜索。相当于给Agent开了一个“工具商店”，常用工具摆在货架前排，冷门工具自己去仓库找。
技能描述本身的写法也决定上下文占用。我建议每条description控制在200个汉字以内，只写明使用条件和关键参数语义。那些长篇大论的注意事项、示例输入输出，应该是开发者文档的内容，不能塞给模型看——不然五六个技能就把prompt撑爆了，真正留给业务上下文的空间变少。
2.4 可观测性与权限边界设计
调用链的追踪是工程化落地的关键。我在每个技能执行点都放置了一个高频打点器，记录四项内容：技能名称和版本、实际入参快照、返回值摘要、耗时与token开销。打点数据进异步队列，不阻塞主流程。初期直接用同步日志，结果高并发压测把磁盘IO干满了，后来改成批量上报才能控住。
权限边界也同样重要。技能层必须有能力区分“只读技能”和“写技能”。比如查询报表是只读，发送邮件是写操作，删除记录就是高风险操作。agent-skills的注册信息里有一个risk_level字段，默认所有技能都是low。写技能必须声明为medium或high，执行器在模型要求调用时，会先走一次策略检查，必要时强制要求用户二次确认。不做这层保护的话，模型一旦被诱导连番触发写操作，后果很难收拾。
3. 核心实现细节与关键代码解析
3.1 技能定义的标准写法
技能定义我采用了装饰器模式，最大的优势是强制无状态。开发者只需要提供一个普通函数，不必继承某个基类或者维护一个技能对象实例。这样技能天然可重复调用，不会因为几次调用之间残留状态而出现“第二次跑结果跟第一次不一样”的老大难问题。
一个典型的技能定义长这样：
from agent_skills import skill @skill.register( name="send_email", description="发送电子邮件，适合需要通知、报告或告警的场景。收件人必须是非空的邮箱地址。", schema={ "type": "object", "properties": { "to": {"type": "string", "description": "收件人邮箱地址"}, "subject": {"type": "string", "description": "邮件标题"}, "body": {"type": "string", "description": "邮件正文，支持纯文本"}, }, "required": ["to", "subject", "body"], }, tags=["email", "notification"], cacheable=False, timeout_ms=30000, risk_level="medium", ) def send_email(to: str, subject: str, body: str) -> dict: # 实际业务逻辑：走某个邮件服务的可用接口 return dispatch_email(to, subject, body)这个函数体足够干净，因为它只管“发邮件”这一个动作。参数已经被Schema层和适配器归一化，函数拿到的to、subject、body一定是正确的字符串类型——除非业务代码自己写崩了，否则参数类错误不会进入函数内部。
3.2 Schema校验与参数归一化
模型返回的工具调用参数，远比你想象的更不可靠。我见过模型把"to"字段传成数组，把"count": 5写成"count": "five"，甚至把必填字段整个遗漏。如果不对参数做严格校验，技能执行层会陷入一种低效重试循环：调用失败，报错信息返回模型，模型猜一个参数再试，又失败，白白烧掉大量token。
因此agent-skills在执行技能前内置了两道关卡。第一道是JSON Schema校验，基于注册定义逐字段检查类型与必填项，不通过直接返回结构化错误，错误信息会明确告诉模型“哪个字段缺失，期望什么格式”。第二道是参数归一化，每种技能可以声明一个normalizer函数，做类型强制转换和格式统一。比如把时间字段统一成ISO 8601字符串，把数字字段从字符串解析成整数，把逗号分隔的标签拆成数组。
参数归一化的一个典型例子是“时间段”参数。用户可能说“昨天”“最近三天”“从5月1日到5月10日”，接入的语义解析模型输出什么格式都有可能。在技能侧统一接收一个range_start和range_end两个绝对时间戳，由编排层在调用前完成相对时间的换算。这样做的好处是，技能内部永远不需要关心自然语言里隐含的时区、节假日偏移等逻辑，只处理标准化输入。
3.3 适配器层与执行器的分工
执行器是整个管道的枢纽，具体职责是：根据用户输入匹配候选技能；把内部技能定义转换成当前模型平台需要的Tools参数格式；接收模型返回的工具调用请求；调用技能函数并回传结构化结果。
适配器层是这里最值得投入设计的地方。不同平台对Tools参数的JSON结构要求确实不一样，例如有的平台用function嵌套name和arguments，有的平台要求tool_choice单独声明。我在内部维护了一套统一Schema，然后为每个平台各写一个几十行的转换器。新增平台时，只需要实现两个方法：internal_to_platform(skill_def)和platform_call_to_internal(raw_tool_call)。
反过来，执行器对技能函数返回结果也做了统一封装。无论函数返回的是字符串还是结构化字典，执行器都会统一包装成带有result键的JSON回传给模型。这样模型在下一步推理时能稳定读取到固定的结果结构，不会因为某种技能返回一个纯文本就语无伦次。
3.4 幂等设计、超时控制与重试策略
写技能（发送通知、修改数据、调用第三方写接口）都必须考虑幂等。模型在对话流程中可能会出于各种原因重复调用同一个技能——第一次超时了，用户催了一句，模型再调一次。如果这个技能是“转账”或者“发送短信”，副作用就会双倍产生。
我在技能层引入了一个可选参数request_id，执行器每次发起调用前自动生成，并且在技能执行过程中，先查一次“事件表”看这个request_id是否已经处理过。处理过就直接返回上一次的结果，不重复执行。这个设计不必每个技能都接入，但所有写技能和涉及扣费的读改写流程，建议一律开启。
超时控制采用“全局默认值+单技能覆盖值”的策略。全局默认设置15秒超时，长时间运行的任务单独指定timeout_ms=120000。为什么单独设置这么重要？因为大文件导出类技能如果也按照15秒掐断，会频繁触发超重试，反而把事情搞得更糟。重试策略我推荐梯度重试：第一次失败后隔1秒重试，第二次隔4秒，第三次直接放弃并返回错误。重试次数超过三次的意义不大，模型会进入死循环式猜测。这个阈值是压测后得到的感受，低于三次成功率不足，高于三次成本过高。
4. 实操：从零到一跑通一个Agent技能编排
4.1 最小可运行示例
如果你在本机尝试运行agent-skills，我建议先用两个内置的演示技能跑通整体链路。演示技能一个是query_daily_sales，用来查最近一段时间的销售汇总；另一个是send_email，用来发送结果邮件。
启动代码很简洁：
from agent_skills import SkillRegistry, AgentRuntime registry = SkillRegistry() registry.scan("skills") runtime = AgentRuntime( registry=registry, platform="platform_a", model="default-model-name", ) resp = runtime.chat("查一下最近三天的销售数据，整理成摘要后发到某个管理者的邮箱") print(resp)这个例子里，模型会自动完成两个技能的接力：先解析出“最近三天”这个相对时间，调用query_daily_sales拿到报表数据，再结合用户提到的收件人信息调用send_email。表面上看起来像是模型突然“会思考”，但实际上每一步都是由技能描述和Schema驱动的。
注意输出里我刻意用了platform="platform_a"的抽象——真实项目里这个参数对应你已经写好的适配器实现，一旦要切换到另一个平台，只要保证平台名对应关系正确，技能层代码完全不用变。
4.2 技能组合的两种形态：原子型与复合型
把技能做得足够小之后，就需要考虑怎么组合它们。简单的组合发生在模型推理层：用户任务包含多个子目标，模型按顺序依次触发多个原子技能。比如“查看销售数据并发送邮件”，这中间的query_daily_sales和send_email都是原子技能，调用顺序由模型自主决定。
但有些流程必须固定顺序，不能让模型自由发挥。比如“生成每日报告”，先查数据、再聚合成摘要、最后发邮件，三步缺一不可、顺序不能乱。这种情况我建议写一个复合技能，通过工作流编排把原子技能串起来，对外只暴露一个generate_daily_report接口。复合技能内部可以调用注册中心里的其他技能，这样既保留了原子技能的复用性，也保证了关键流程的确定性。
实操中，复合技能经常被设计成一个“计划者”技能——先让Agent调用它，它内部把任务分解成子步骤，再按顺序逐一触发原子技能。有一个细节：复合技能的description一定要写清楚它在什么条件下使用，避免模型绕过原子技能直接意图不明确地乱调用。我一度把generate_daily_report的描述写得过于宽泛，结果模型在用户只想“看一下昨天数据”的时候也去触发报告生成，白白发了一封邮件。
4.3 压测之前先检查的三件事
跑通链路只是起点，真正能上线还要做一轮针对性压测。我建议至少检查三件事：技能匹配成功率、上下文消耗、并发注册中心的线程安全性。
技能匹配成功率是衡量description质量的指标。准备一百条近似真实用户的随机意图，把这些意图分别发给Agent，统计模型是否选择了正确技能。第一次测试我的匹配成功率只有六成，原因是技能描述里用了过多内部术语，比如“调取营销归因模型数据”，而用户说的是“看看这次活动带来多少单”。把描述改成贴近用户表达以后，成功率到了九成以上。
上下文消耗统计的是每轮调用大约吃掉了多少token。你可以专门定制一版日志，在每轮结束记录prompt_tokens与completion_tokens。如果发现工具定义占的比例过高，就按2.3节的做法做技能分组与裁剪。并发场景下，注册中心的scan和技能查询应该都是只读操作，我加了读写锁，保证热加载新技能时不会出现“查到了注册表内容但不完整”的问题。
5. 常见问题与排查技巧
5.1 问题速查表
| 问题 | 现象 | 常见原因 | 解决办法 |
|---|---|---|---|
| 技能不生效 | 模型说无法调用某个技能 | 技能描述缺少用户同义表达 | 扩充描述，贴近用户口语 |
| 参数校验失败 | 调用报错但模型不改参数 | 缺少参数归一化步骤 | 配置normalizer做类型转换 |
| 上下文溢出 | 请求直接超长报错 | 技能全量注入 | 分组裁剪、延迟加载、二级技能 |
| 技能循环调用 | 同一个技能被连续触发多次 | 返回结果没有正确回传 | 检查执行器回传逻辑 |
| 重复副作用 | 邮件或通知发送了两遍 | 缺少幂等机制 | 引入request_id事件表 |
| 旧技能残影 | 模型调用一个已被废弃的技能 | 扫描器加载了备份目录 | 配置排除规则 |
5.2 一个典型的“技能时灵时不灵”排查过程
有一次，测试同学反馈某个查询技能“时而能用、时而不能用”。我盯着日志看了一会儿，发现触发成功的对话里包含技能描述里的关键词，触发失败的对话里用户换了另一种表达。问题不在模型推理能力，而在于技能的description没有覆盖用户可能的表达方式。
排查的基本思路是：先看技能是否被成功注入到工具列表里，再核对模型返回的tool_call中的name，最后看技能执行结果。任何一环没有出现，都说明问题出在那一层之前的链路。日志里如果同时有“skill_loaded”和“tool_call_miss”两个标记，基本可以断定是技能匹配阶段出了问题。
修法也很直接：把用户侧高频说法列出来，反向扩充description的同义表达。不是让你堆砌关键词，而是围绕“这个技能到底服务于什么意图”来写。比如“查询销售数据”，不妨写清楚“支持按时间范围汇总销售额、订单量、客单价，也可以按区域或渠道拆分”——让模型看到描述就知道“这里有它要的维度”。
5.3 几个平时文档里不怎么会写的细节
我在实际跑项目时有几个印象深刻的细节，分享在这里。
第一是别让required字段管得太宽。Schema里必填字段越多，模型就越容易因为缺一两个字段而反复尝试、反复失败。只有真正不可缺的参数才放进required，其余参数尽量给默认值。第二是要为每次技能调用保留原始入参快照，包括模型生成的原始参数和归一化之后的参数。后续复盘Agent决策链，没有这两份数据几乎是盲复盘。第三个细节是技能执行函数的日志格式必须结构化——直接写人类可读的字符串会很难检索，统一成JSON单行日志会让排查效率高得多。
还有一点关乎安全：不要给Agent暴露“执行任意SQL”或“执行任意Shell命令”这类泛化技能。你需要把这些能力封装成参数受限的技能，比如只允许查询特定视图、只允许在指定目录下创建文件。否则一个越狱指令就可能让模型借技能之手做越权操作，这是我在权限边界上反复做过强约束的领域。
6. 后续扩展方向
技能库做到后面，越来越像一个小型内部服务市场。我目前正在尝试给agent-skills加两个扩展：一个按技能调用频率生成“冷热排行榜”，高频技能自动排列在提示词工具列表的前排；另一个是针对技能质量本身做回归测试，每次技能描述改了之后，自动跑一遍覆盖用例，防止“修好一个描述、弄坏另一个场景”。
如果你也在打磨Agent工具层，建议先从最小技能集开始，把两三个高频流程用这套方式管起来，再逐步扩展规模。做这层工程化确实要花时间，但它能让你后续的Agent迭代变得特别清爽：加新能力、换模型、追问题，都不再是一团乱麻。
