Agent Skills 架构实战：从技能设计到调度落地的完整指南

1. 从会聊天的模型到能交付的智能体Agent Skills 到底在解决什么很多人第一次接触 Agent 这个概念脑子里浮现的是一个能对话的机器人。但真正做过 Agent 项目的人都知道对话只是最表层的东西。一个能真正干活的 Agent核心难点从来不是它能不能理解你说的话而是它能不能在正确的时机、用正确的方式、调用正确的工具把一件事从头到尾做完。这中间的差距就是 Skills 存在的意义。我先把结论摆在前面Agent Skills 本质上是把技能从 Agent 的推理逻辑里剥离出来做成可独立描述、可独立加载、可独立复用的能力单元让 Agent 变成一个技能调度器而不是什么都得自己现学现卖的全能选手。这个思路听起来简单但它带来的架构变化是根本性的。为什么这么说你可以把没有 Skills 的 Agent 想象成一个刚入职、什么都得靠临场发挥的员工。你问他帮我处理一下这张图片他得自己琢磨用什么库、走什么流程、输出什么格式。每次遇到类似任务他都要重新推理一遍。而有了 Skills 之后相当于给这个员工配了一本随时可查的操作手册库每本手册对应一类任务的标准做法他只需要判断这是哪类任务然后翻开对应手册照着执行就行。这个转变带来的直接好处有三个。第一是稳定性标准做法被固化下来不会因为模型每次推理的随机性导致结果飘忽。第二是可维护性某个技能要升级只改那个技能文件不用动 Agent 的核心逻辑。第三是可组合性复杂任务可以拆成多个技能串联像搭积木一样拼出工作流。从热词里能看到大量相关信号——claude code 怎么手动装 github 上的 skills、codex skills、opencode skills、常用 skills 源网站、skills 技能库网址。这说明一个很现实的需求已经出现了大家不再满足于有个 Agent 能用而是想要有一套技能库能装、能换、能共享。这跟当年前端从手写 jQuery进化到npm 装包是同一个逻辑——能力要被工程化、被标准化、被分发。所以这篇内容我想聊的不是Agent 是什么这种入门问题而是Skills 架构下的 Agent 到底该怎么理解、怎么设计、怎么落地。适合已经动手写过 Agent、或者正准备把 Agent 从 Demo 推向生产的人看。如果你还在纠结要不要用 Agent那可能先补一下基础会更顺。2. Skills 与 Agent 的职责边界谁负责思考谁负责执行2.1 一个常见的架构误区把所有逻辑塞进 Prompt我见过太多 Agent 项目打开一看系统提示词写了三千字里面塞满了当用户要求 A 时你要这样做当用户要求 B 时你要那样做。这种写法在 Demo 阶段能跑通但一旦技能数量超过十个就会彻底失控。原因很简单Prompt 是线性的文本而技能是并行的能力集合用线性结构去管理并行能力必然爆炸。正确的做法是把职责切开。Agent 的核心职责只有三件事理解用户意图、判断需要哪些技能、编排技能的执行顺序。至于这个技能具体怎么实现完全交给 Skill 自己描述。这就是 Skills 架构的第一性原则——关注点分离。打个比方Agent 像是一个项目经理Skills 像是各个专业工种的作业指导书。项目经理不需要会砌墙、会布线、会刷漆他只需要知道这个活需要瓦工、电工、油漆工然后按顺序把人叫来。如果项目经理非要把所有工种的细节都背在脑子里那他不是项目经理他是个累死的全栈工人。2.2 Skill 描述文件应该包含哪些字段一个能被 Agent 正确调度的 Skill它的描述文件至少要回答四个问题这个技能是干什么的description、什么时候该用它when to use、用的时候需要什么输入inputs、会产出什么结果outputs。这四个字段缺一不可。我实测下来最容易出问题的是when to use这个字段。很多人只写这个技能用于处理图片太模糊了。Agent 面对帮我压缩一下这张图和帮我把这张图转成素描风格两个请求时如果技能描述不够精确它可能两个都匹配到同一个技能或者两个都匹配不上。好的写法应该是把触发条件写具体比如当用户需要对图片进行格式转换、尺寸调整、质量压缩时使用把边界划清楚。下面是一个技能描述的结构示例用 YAML 表达比较直观name: image-resize description: 对图片进行尺寸调整和格式转换 when_to_use: | 当用户提出以下需求时使用 - 修改图片的宽高尺寸 - 转换图片格式如 png 转 jpg - 按比例缩放图片 不适用于风格迁移、滤镜处理、内容识别 inputs: - image_path: 源图片路径 - target_width: 目标宽度可选 - target_height: 目标高度可选 - format: 目标格式可选 outputs: - output_path: 处理后的图片路径注意when_to_use里我特意写了不适用于的部分。这一点非常关键明确排除项比明确包含项更能提升调度准确率。因为 Agent 在匹配时模糊地带才是误判的高发区。2.3 为什么技能粒度决定了整个架构的上限技能拆得太粗一个技能干十件事那 Agent 调度时就没法灵活组合等于没拆。技能拆得太细一个技能只干一件微不足道的小事那 Agent 光调度开销就压垮了而且技能之间的依赖关系会变得极其复杂。我的经验是一个 Skill 应该对应一个完整的、有明确交付物的动作。比如读取 Excel 并解析成结构化数据是一个合理的粒度打开文件和读取第一行就太细了处理所有办公文档又太粗。判断标准很简单如果这个技能产出的东西是下一个技能可以直接消费的那粒度就对了。从热词里harness 和 agent 区别、harness 架构langchainlanggraph智能体开发案例这些搜索能看出很多人正在纠结框架层面的选型。但我想说的是框架只是承载 Skills 的容器真正决定 Agent 好不好用的是技能怎么切分、怎么描述、怎么编排。框架选错了可以换技能设计烂了换什么框架都救不回来。3. 技能加载与调度机制Agent 怎么知道自己会什么3.1 技能注册的两种模式全量加载与按需检索Agent 要调用技能首先得知道有哪些技能可用。这里有两种主流模式各有适用场景。全量加载是把所有技能的描述一次性塞进上下文让模型在推理时自己选。这种模式实现简单适合技能数量少比如 20 个以内的场景。但它的致命问题是上下文占用——每个技能描述按 200 字算50 个技能就是一万字还没开始干活上下文就被吃掉一大块而且模型在长列表里的选择准确率会明显下降。按需检索是先做一个技能索引用户请求进来后先用检索关键词匹配或向量相似度筛出最相关的几个技能再把这几个技能的详细描述喂给模型。这种模式扩展性好技能上百上千都不怕但多了一层检索就多了一层误召回的风险。我实际项目里的做法是混合模式把技能按领域分组先做粗粒度的领域路由再在领域内做细粒度的技能匹配。比如用户说帮我处理一下这个表格先路由到数据处理领域再在这个领域里匹配到Excel 解析或CSV 清洗等具体技能。这样既控制了上下文长度又保证了匹配精度。3.2 技能匹配失败时的兜底策略再好的匹配机制也会有失手的时候。用户的需求千奇百怪总有技能库覆盖不到的情况。这时候 Agent 该怎么办直接说我不会是最差的体验。我的做法是设置三级兜底。第一级是近似技能推荐匹配不到精确技能时返回最接近的几个让用户确认是不是想要这个。第二级是通用能力降级如果确实没有对应技能但任务本身在模型的基础能力范围内比如简单的文本总结就直接用模型原生能力处理不强行套技能。第三级是技能缺口记录把匹配失败的请求记下来作为后续补充技能库的依据。这个兜底链路看起来是小事但它直接决定了 Agent 是越用越好用还是永远就那几招。技能库的迭代靠的就是这些失败案例的积累。3.3 多技能编排串行、并行与条件分支单个技能调用只是起点真实任务往往是多个技能的组合。这里就涉及到编排逻辑。串行编排是最常见的技能 A 的输出作为技能 B 的输入一条链走到底。比如下载图片 → 压缩图片 → 上传到指定位置。并行编排适合互不依赖的子任务比如同时处理多个文件能显著缩短总耗时。条件分支则是根据中间结果决定下一步走哪条路比如如果图片是竖版就按竖版规则处理否则按横版规则处理。编排逻辑写在哪里我的建议是写在 Agent 的调度层而不是写在某个技能内部。技能应该保持单一职责编排是调度层的事。这样技能才能被不同流程复用否则每个技能里都嵌一套流程判断复用性就没了。从热词agent execution terminated due to error能看出执行中断是大家常遇到的问题。编排层必须处理异常某个技能失败了是重试、跳过、还是终止整个流程这个策略要在编排时就定义清楚不能等出错了再临时想。我一般会给每个技能调用设置重试次数上限和超时时间超过就按预设策略走避免整个流程卡死。4. 从零搭一个 Skills 架构 Agent 的实操路径4.1 环境与依赖准备中最容易忽略的细节动手之前先把基础环境理清楚。这里我不绑定具体框架讲通用的准备逻辑。首先是运行环境。Agent 要调用技能技能可能要执行代码、访问文件、发起网络请求所以运行环境需要有相应的权限和依赖。我踩过的一个坑是本地开发时一切正常部署到服务器后技能全部失败排查半天发现是服务器上没有装某个技能依赖的系统库。技能依赖要显式声明不能靠本地碰巧有。其次是技能目录结构。建议按领域分目录每个技能一个文件夹里面放描述文件和实现代码。这样加载时按目录扫描新增技能就是新增文件夹非常清晰。下面是一个我常用的目录结构skills/ >