1. 从agent-skills这个命名说起它到底指什么第一次看到agent-skills这个词很多人会下意识地把它理解成某个具体的库或者框架。但如果你在工程实践里摸爬滚打过一段时间就会发现它更像是一个能力组织范式而不是一个能直接pip install的包。这个命名本身透露出的信息量其实很大agent 是主体skills 是主体所具备的能力集合两者之间是拥有和被拥有的关系。换句话说它讨论的核心问题是——一个智能体应该以什么样的结构去承载、调度和复用它的各项能力。我在早期做对话系统的时候能力是散落在各处的意图识别一个模块、工具调用一个模块、记忆管理又一个模块彼此之间靠硬编码的 if-else 串联。项目一旦膨胀改一处就牵动全身。后来接触到把能力抽象成 skill的思路才意识到问题的根源不在于模块多少而在于缺少一层统一的能力描述与注册机制。agent-skills 要解决的正是这层机制该长什么样。所以这篇内容适合谁看如果你正在设计一个需要调用多种外部工具、需要维护多轮上下文、并且未来还要不断加能力的智能体系统那这里讨论的结构问题你迟早会撞上。如果你只是想跑一个单轮问答的 demo那确实用不上这么重的设计。我下面会从能力抽象、注册调度、上下文传递、失败处理几个角度把我在实际项目里踩过的路讲清楚尽量让你少走弯路。需要先说明一点agent-skills 目前并没有一个被广泛标准化的官方规范不同团队对它的实现差异很大。我下面讲的是基于常见工程实践总结出的一套相对通用的做法你可以把它当成设计参考而不是唯一答案。2. 把能力拆成 skill抽象粒度决定系统上限2.1 为什么不能把一个函数直接当成一个 skill最省事的做法是把每个工具函数直接注册成一个 skill比如search_web、send_email、query_db各算一个。这样做的短期收益很明显——注册逻辑简单调用路径短。但我实测下来这种粒度在能力数量超过二三十个之后会迅速失控。原因有三个一是语义重叠search_web和search_news在意图层面几乎无法区分模型选择时容易摇摆二是参数爆炸每个函数都有自己的参数签名模型要在几十个签名里做匹配出错率陡增三是复用困难两个 skill 共享的鉴权、重试、限流逻辑无处安放只能复制粘贴。我的经验是skill 的粒度应该对齐用户可感知的完整任务单元而不是对齐代码里的函数边界。举个例子查询某只股票的当前价格是一个 skill它内部可能调用了行情接口、做了字段清洗、还处理了异常兜底但对上层来说它就是一个原子能力。这样模型在做选择时面对的是语义清晰的任务而不是一堆技术函数。2.2 一个 skill 应该包含哪些描述字段既然 skill 是任务单元那它的描述就必须足够让调度层看懂。我在项目里固定下来的字段大致是这几类你可以对照自己的场景增删字段作用是否必填name唯一标识建议用动词开头的短横线命名必填description自然语言描述直接喂给模型做选择必填parameters参数 schema含类型、是否必填、默认值必填examples典型调用示例帮助模型对齐意图强烈建议permissions所需权限或前置条件视场景timeout单次执行超时建议其中description 的写法是最容易被低估的。很多人写得像 API 文档比如调用天气接口返回温度。但模型需要的是什么时候该用它的语义线索。我通常会把 description 写成当用户询问某地当前或未来天气时使用输入城市名返回温度、湿度和天气状况。多花两分钟写清楚触发条件能显著降低误调用率。2.3 参数 schema 的设计陷阱参数设计里有个反直觉的点参数越少模型越不容易出错。我见过一个 skill 有八个参数其中五个是可选的结果模型经常漏填关键参数或者填错类型。后来我把这个 skill 拆成两个——一个快速查询只带必填参数一个高级查询才暴露全部参数。拆分之后调用成功率肉眼可见地上升。另一个坑是枚举值不要用中文。模型对枚举的匹配在英文短标识上更稳定比如unit: celsius | fahrenheit就比单位: 摄氏度 | 华氏度靠谱。展示层再做一次映射即可没必要让模型直接处理本地化字符串。3. 注册与调度让模型知道有哪些能力可用3.1 能力清单是怎么进入模型视野的skill 定义好了接下来的问题是模型怎么知道现在有哪些 skill 可用常见做法有两种。一种是把所有 skill 的描述拼成一段文本塞进系统提示词另一种是通过工具调用tool calling的原生接口传入结构化列表。前者兼容性好但会吃掉大量上下文后者更省 token 但依赖模型支持。我一般会做分层暴露把 skill 按领域分组先让模型选领域再在领域内选具体 skill。这样单次进入上下文的 skill 数量能控制在十个以内选择准确率明显更高。如果能力总数不多比如十五个以内直接全量暴露也没问题不必过度设计。提示无论用哪种方式skill 的 name 和 description 都会占用上下文预算。能力越多留给对话本身的空间越小。这是设计时必须权衡的硬约束。3.2 调度层到底该做多少事调度层最容易犯的错是什么都想管。我早期写过一个调度器它要判断意图、要校验参数、要决定重试、还要拼装结果最后代码复杂到没人敢改。后来我把它砍到只做三件事接收模型的 skill 选择、校验参数合法性、把执行结果原样回传。至于重试、降级这些下沉到每个 skill 自己的实现里。这样切分的好处是职责清晰调度层是路由器skill 是执行者。路由器不需要懂业务执行者不需要懂全局。当你要新增一个能力时只写 skill 本身完全不用碰调度层。这个边界一旦立住系统的可维护性会有质的提升。3.3 参数校验放在哪一层参数校验我建议做两道。第一道在调度层只做最基础的检查——必填项是否缺失、类型是否匹配。这道校验的目的是快速失败避免把明显错误的调用送进 skill。第二道在 skill 内部做业务级校验比如日期不能晚于今天金额必须为正数。这两类校验的性质不同前者是协议层的后者是业务层的混在一起会让代码难以定位问题。我踩过的一个坑是把业务校验也放到调度层结果调度层里堆满了各种业务规则最后它变成了一个隐形的业务中心。这违背了分层的初衷。记住调度层只认格式对不对不认业务上合不合理。4. 上下文与状态多轮场景下最容易翻车的地方4.1 skill 之间怎么传递中间结果单轮调用很简单模型选一个 skill执行返回。但多轮或者链式调用时中间结果怎么传就成了大问题。我见过两种极端一种是把所有历史结果都塞进上下文导致 token 迅速膨胀另一种是每个 skill 各自维护状态结果彼此对不上。我的做法是引入一个轻量的会话状态对象skill 执行完把关键产出写进去下一个 skill 需要时从里面读。这个对象只存结构化的事实比如用户当前查询的城市是杭州上一步得到的订单号是 X而不是存原始的自然语言回复。这样既保证了信息可传递又不会让上下文失控。4.2 什么时候该清空上下文上下文不是越多越好。实测下来当对话轮次超过一定数量后早期信息对当前决策的贡献急剧下降反而会干扰模型判断。我会设置一个滑动窗口只保留最近若干轮同时把被移出窗口的关键事实压缩成一句话摘要保留。这样既控制了长度又不丢重要信息。具体窗口设多大没有标准答案。我的经验值是如果 skill 调用频繁窗口可以小一些比如六到八轮如果对话以闲聊为主偶尔调用窗口可以大一些。这个参数值得在真实流量上做 A/B 测试而不是拍脑袋定。4.3 状态一致性怎么保证链式调用里最怕的是上一步的结果被下一步覆盖了。比如用户先查了 A 订单又查了 B 订单如果状态对象里只有一个order_id字段那 A 的信息就丢了。解决办法是用带命名空间的结构比如orders.current和orders.history而不是一个扁平的字段。这样即使同名信息出现多次也不会互相踩踏。另一个隐患是并发。如果同一个会话里有两个 skill 同时执行并写状态就可能出现竞态。我的处理方式是给会话状态加一个简单的写锁或者干脆串行化同一会话内的 skill 执行。对大多数场景来说串行带来的延迟增加是可以接受的换来的是状态的可预测性。5. 失败处理skill 报错之后系统该怎么办5.1 区分可重试和不可重试的错误skill 执行失败是常态关键是怎么分类。我通常把错误分成三类瞬时错误网络抖动、限流、参数错误模型填错了参数、业务错误业务规则不允许。瞬时错误可以自动重试参数错误应该把错误信息回传给模型让它重新填业务错误则要直接告诉用户原因。如果不做这个区分一律重试那参数错误会无限重试直到超时一律不重试那网络抖动就会白白浪费一次调用。分类处理是性价比最高的一步优化。5.2 错误信息怎么回传给模型这里有个细节很多人忽略回传给模型的错误信息要可操作。比如不要只说参数错误而要说参数date格式应为 YYYY-MM-DD你传入的是 2024/01/01。模型拿到这种信息后往往能自己纠正并重新调用。我实测过把错误信息写具体之后模型自我修复的成功率能提升不少。但也要注意别把内部堆栈直接暴露给模型那既浪费 token 又可能泄露实现细节。对外只给用户能理解、模型能利用的那一层信息就够了。5.3 降级策略的设计当某个 skill 持续失败时系统需要有降级路径。最简单的降级是告诉用户暂时不可用但更好的做法是准备一个能力相近的备用 skill。比如主搜索 skill 挂了切到备用搜索源。这要求在设计阶段就把同类能力归组而不是等出事了才临时找替代。降级还有个隐性成本备用 skill 的返回格式可能和主 skill 不一致导致下游解析出错。所以我在定义 skill 时会尽量让同类 skill 的输出结构保持统一这样切换时下游无感。6. 实测中总结的几条经验6.1 skill 数量不是越多越好我一度以为能力越丰富系统越强于是拼命加 skill。结果发现当数量超过某个阈值后模型的选择准确率开始下降而且下降得比想象中快。后来我做了减法把低频、语义模糊的 skill 合并或下线整体表现反而更好。能力建设要做加法但能力治理必须做减法。6.2 description 要定期回看skill 的 description 不是写完就一劳永逸的。随着业务变化它的语义边界可能已经漂移。我会定期把线上真实的调用日志拉出来看看哪些 skill 被误调用最多然后针对性修改 description。这个习惯帮我解决过好几次模型总是选错 skill的问题。6.3 给 skill 加一个试运行模式上线新 skill 之前我会先让它以只记录不执行的模式跑一段时间观察模型在什么场景下会选中它、参数填得对不对。确认无误后再真正放开执行。这个灰度过程能挡掉大部分低级错误比直接上线再回滚要省事得多。6.4 日志要记到能复现的程度排查 skill 问题时最怕日志里只有调用失败四个字。我会确保每次调用都记录选中的 skill、传入的参数、返回的结果或错误、耗时。有了这些任何一个线上问题都能在本地复现。日志的详细程度直接决定了你排障的速度。7. 关于扩展方向的一点个人看法agent-skills 这套结构跑通之后往哪个方向长其实取决于你的场景。如果你的 skill 之间经常需要组合那可以考虑引入技能编排——让模型不只是选单个 skill而是能规划一个 skill 序列。如果你的 skill 需要访问敏感资源那权限体系就得单独设计把能调用和有权调用分开。我自己目前更关注的是 skill 的可观测性也就是怎么在不增加调用方负担的前提下把每个 skill 的健康度、成功率、延迟都监控起来。这块做扎实了系统才敢真正放到生产环境里长期跑。这套东西没有银弹每个团队的业务形态不同最优解也不同。但有一条是共通的先把能力的边界划清楚再谈调度和优化。边界不清后面所有的设计都是在流沙上盖楼。