从能回答到能做事：Agent技能层设计与实践解析

从“能回答”到“能做事”：Agent技能层到底卡在哪

过去大半年，我一直在折腾AI代理（Agent）的东西。最直观的感受是：现在的大模型单拿出来都很聪明，能写诗、能解题、能聊天，但如果你让它“自动把一份表格里的数据整理成周报并发送到群里”，它往往会在第一步就卡住——要么把表格读错了，要么不知道怎么发到群里，要么干脆自己编一个结果给你。

问题的核心不在模型，而在“技能”。

所谓agent-skills，简单说就是给Agent准备的一套可复用、可组合、可校验的“行为能力模块”。有了这些模块，Agent不再靠每次对话时临场发挥去猜测用户意图，而是像人类员工一样，有明确的工作流程、操作手册和经验积累。这个项目要解决的就是一件事：让Agent真正从“会说话”进化到“会做事”。

这篇文章不聊那些花哨的框架和概念，我把自己的设计思路、代码结构、踩过的坑，以及几种适合不同场景的玩法，全部摊开来讲。适合正在做Agent应用开发、或者想给现有LLM应用加上自动化能力的人参考。

1. 为什么Agent需要独立的技能层

先说个经常被误解的点：很多人以为Agent能力不行，是模型不行，所以拼命换更大的模型。实际上，在复杂任务里，模型占的权重可能只有四成，剩下六成在任务拆解、工具调用、状态记忆和异常恢复上——这些都属于技能层的范畴。

1.1 让Agent具备“肌肉记忆”而不是“临场发挥”

大模型本质上是靠概率生成下一个token的引擎。如果你的Agent每次执行某类任务都要重新推理“我应该怎么读取Excel”，那它不但慢，而且每次推理的路径都可能不一样，极其不稳定。

技能层的核心价值，就是把那些高频的、稳定的操作固化成“标准动作”。比如：

• 读取文件并解析为结构化数据
• 调用搜索接口并抽取关键结果
• 按模板生成报告并渲染
• 读取数据库并执行指定查询

这些动作的输入输出是明确的、边界是清晰的、逻辑是可复现的。Agent需要做的只是“选择合适的技能去执行”，而不是每次从头开始“发明”一套方案。

1.2 技能层如何降低系统复杂度

没有技能层，Agent的调用关系往往是网状的一团乱麻：任务逻辑、工具调用、错误处理、参数转换全搅在一起。有了技能层，调用关系就变成了星型结构：中央调度器面向技能注册中心，按需选用合适的能力。

从工程角度，这带来的好处非常直接：

• 新增能力时不需要改动Agent主逻辑，只需添加一个技能
• 技能可以单独测试、单独替换，不会牵一发动全身
• 不同的Agent实例可以共享同一套技能库，保持行为一致性
• 技能执行的日志和指标可以统一采集，方便观察Agent内部的每一步

1.3 适合谁来用这套思路

这个方案不是给研究大模型算法的人看的，更偏工程实现。如果你正在做以下任意一类事情，它大概率对你有帮助：

• 做企业内部的知识库问答，并希望把问答延伸到“执行操作”而不是只返回文本
• 做个人助理类的Agent，让它能操作各种工具和应用
• 做行业垂直的自动化流程，想用自然语言作为交互入口但又希望底层可控
• 做多Agent协作系统，需要给不同角色的Agent分配不同能力

换句话说，只要你的Agent需要“动手做事”而不是“动嘴聊天”，技能层就是绕不开的一道坎。

2. 技能层的整体设计与核心要素

我在设计技能层时，参考了人类职业技能培训的思路。一个成熟的技术岗位，不会让你靠一腔热血去干活，而是会给你岗位说明书、操作SOP、工具清单和质量标准。技能层的设计也是这样。

2.1 一份技能注册信息长什么样

每个技能在Agent系统中都需要被“登记在册”，这部分我习惯称之为“技能元数据”。它描述的是：这个技能是干什么的、什么时候用、参数是什么样子、有什么使用限制。

我常用的技能注册结构如下：

skill: name: excel_analyzer description: 读取Excel文件并输出结构化统计结果，适用于数据分析、报表生成场景 version: 1.2.0 author: agents-team license: internal-only tags: [excel,># 反例：几乎等于没约束 input_schema: query: type: string # 正例：边界清晰、默认安全 input_schema: query: type: string minLength: 2 maxLength: 500 format: type: string enum: [json, table, text] default: json

3.4 多模型适配：别绑死在一个模型上

我最初以为技能系统只服务一个固定的大模型，后来发现不同客户用的模型五花八门——有人用GPT-4o，有人用Claude，还有人用国产开源模型。不同的模型对长文本的理解能力、工具调用的遵守程度差得很大。

应对多模型适配，我做了两个调整：

第一，技能描述尽量简短清晰。有些模型上下文处理能力弱，描述一长就开始忽略细节。每个技能的描述控制在150字以内，一句“何时用”，一句“能做什么”，一句“不负责什么”，坚决不写废话。

第二，增加“提示词模板覆盖”机制。不同模型对工具调用的指令理解方式不同，我会针对主流模型准备不同的调度提示词模板，但内部技能实现是同一套。这样模型变了，技能不用动；技能变了，模板不用动。

4. 技能编排与Agent执行的关键环节

有了技能库，下一步就是让Agent能在合适的时机使用合适的技能。这里的核心是调度策略和上下文管理。

4.1 技能匹配：用语义检索降低误选率

如果技能数量超过二三十个，直接让大模型从全量列表里挑技能，极易选错。我的做法是在调度前加一个“技能检索器”，先做一轮粗排，再让大模型从候选里精挑。

实现的思路并不复杂：

1. 把所有技能的description向量化，存入向量数据库
2. 在每次Agent收到任务时，对当前任务描述做向量检索
3. 取Top 5~10个候选技能，交给大模型做最终选择
4. 大模型输出技能调用时，进行参数校验，不合法则自动重试一次

加了这层检索后，技能选错率显著下降。不用向量检索时，模型经常在几十个技能里眼花缭乱；用了检索之后，范围缩小了，决策质量明显提高。

4.2 多技能组合：让Agent有“工作流”意识

单个技能解决单点操作，但真实任务往往需要多步串联。比如“把销售数据按月汇总并画成图表”至少涉及：读取数据 → 计算汇总 → 生成图表 → 保存结果。每一步对应一个技能，缺一不可。

多技能组合有两种粒度：

• 显式工作流：预先定义好步骤的顺序和条件，Agent按图索骥执行
• 隐式规划：Agent根据任务目标自行拆解步骤，每步调用相应技能

我的经验是：能显式就显式，别让模型自由发挥太多。特别是企业内部那些流程相对固定的任务，显式工作流是稳定性的最大保障。动态拆解只留给那些确实无法预判的开放式任务。

4.3 上下文管理：执行现场别丢

Agent在执行技能时，最怕的是“走到一半忘了前面的结果”。比如先读取了表格，然后去调用搜索API，搜完之后回头要用表格数据做分析——如果中间的上下文被覆盖，那后面就是灾难。

我在技能执行层加了一个轻量级的“现场记录器”，每次技能执行完，自动把关键输出摘要写入上下文中，让后续步骤可以随时引用。

# 核心：技能执行完自动沉淀摘要 from agent_skills import register_callback @register_callback("post_execution") def persist_summary(exec_ctx, result): summary = { "skill": exec_ctx.skill_name, "output_summary": truncate(str(result), max_length=300), "latency_ms": exec_ctx.latency_ms, "status": exec_ctx.status, } exec_ctx.memory.append("exec_summary", summary)

这套机制解决的最大问题：当Agent需要回溯“我上一步干了什么”时，不用重跑技能，也不用翻大量原始日志，直接从摘要中恢复上下文，速度和稳定性都好很多。

5. 建设过程中的踩坑记录与避坑技巧

这一节是全文最值钱的部分。技能层听起来不难，真做起来坑满地都是。我按踩坑的时间线来回顾，顺便把解决办法一并附上。

5.1 技能描述写得太“文艺”

我在技能描述上翻过最大的车：使用形容词描述行为，比如“快速高效地读取表格”，结果模型完全忽略了这个技能。后来才明白，大模型更偏好有明确触发条件和使用边界的描述，而不是形容词堆砌。

改法也很直接：把“高效”“智能”“灵活”这类词汇全部删掉，换成“当...时”“如果...则”“仅用于...”这类硬逻辑。描述的目标不是看起来专业，而是让模型理解起来零歧义。

5.2 技能超长导致上下文溢出

最初我写的技能配置洋洋洒洒几百行，包括大量使用示例、边界解释、错误码表。结果一个技能就把上下文窗口吃掉一大截，多技能任务直接爆长度。

解决方案是分级存放：核心必备信息（描述、参数、安全约束）留在系统提示词中，完整文档和示例放到外部存储器，仅在模型明确需要时才调出来查看。

5.3 业务逻辑泄漏到技能内部

技能层的设计初衷是“能力与业务分离”，但我一度在技能里直接写死业务判断，比如“如果地区包含华南就不处理”，后来业务一变，技能变成了一坨补丁。

这个问题的正确解法是：技能只做通用操作，具体的业务规则通过参数传入或者在编排层判断。技能保持“能力中立”，才能在不同场景里复用，也才能在业务调整时代码改动最少。

5.4 缺少技能回归测试

很长一段时间，我的技能库只做正向验证：跑通一次就算完成。结果某次更新后，一个技能对特定格式文件的处理出错了，但当时没有任何一轮测试发现，直到线上Agent执行任务失败才暴露。

后来我认真做了回归测试体系，为每个技能维护了多组测试用例，涵盖正常输入、边界输入、异常输入。每次技能库更新，自动跑完全量测试，有失败就直接拦住，不能发布。

技能回归测试的用例设计思路可以参考下表：

5.5 多技能组合时的顺序冲突

组合技能多了之后，出现一种奇特的情况：技能A和技能B单独执行都完美，但A执行完再执行B，结果却异常。定位后发现是状态残留问题——A修改了某个变量，B对变量有预设假设，结果就崩了。

解决方法是制定严格的“技能隔离契约”：技能之间的数据只能通过显式的输入输出传递，禁止依赖共享状态。额外在技能调用入口做状态快照，出问题可以快速回滚。

6. 技能库的版本管理与团队协作

当技能库初具规模后，管理等事本身变成了新问题。我把这套系统给团队里几个人用过，很快就发现：如果一次性修改所有技能，简直就是给自己挖坑。

6.1 版本语义化

技能版本号不推荐随便写。我采用的是语义化版本规范：

• 主版本号：接口不兼容，改动可能导致使用方报错
• 次版本号：向后兼容的功能新增，原有使用方无需改动
• 补丁版本号：内部bug修复，不改变外部行为

每次大改技能描述或参数Schema，主版本号就要变动；新增了一种输出格式，次版本号递增；修了个小bug，补丁版本号递增就行。

这套规则看着简单，实际操作时却能避免非常多混乱。比如模型A调用技能v1.0.0传的参，和模型B调用v2.1.0传的参，兼容性一目了然。

6.2 谁可以改技能

在团队协作时，无节制地允许所有人改技能会导致混乱。初期我们的教训是：三个不同背景的人都改同一个技能，结果互相不兼容，技能库成了一个没人敢动的大杂烩。

后来我引入角色权限模型：

• 使用者（Agent应用开发者）：只能调用技能，不能修改
• 维护者（技能开发者）：可修改技能实现与文档
• 审核者（架构负责人）：负责合并到生产环境

这本质上是一种Code Review制度。技能变更单发起以后，必须经过指定审核人确认才能合并发布。审核重点看三处：描述是否仍然精准、参数校验是否仍然有效、回归测试是否覆盖本次变更。

6.3 技能市场：跨项目复用

当技能库积累到覆盖常用场景后，你会发现很多互不相干的项目会需要同一批技能：文件读写、网络请求、数据分析、消息通知。与其每个项目复制一遍，不如搭一个私有的技能仓库。

这个仓库的作用类似于软件包的私服仓库。技能版本更新后统一发布，项目里通过依赖声明引入。这样有两个好处：一是节省重复开发的成本；二是所有子项目都能享受到修复和优化。

7. 最后聊点个人心得

做 agent-skills 这件事，我最大的体会是：真正难的不是让Agent“聪明”，而是让它“稳”。模型天然带有随机性，如果你把所有希望寄托在模型临场发挥上，结果就只有一个字：赌。技能层的价值恰恰就是对抗这种随机性的——把那些不该随机的事情固定下来，把那些允许随机的事情留给模型去创造。

现在回头看，这个方向在我实际项目里的收益体现在三个地方：一是Agent执行复杂任务的成功率大幅提升，二是调试问题时的定位时间缩短了一个量级，三是接手项目的同事终于不用再靠“问Agent为什么这么做”来维护系统了。

如果看完这篇，你也打算给自己的Agent项目加技能层，我给你一条最现实的建议：先别急着搭大框架，挑一个最高频、最稳定的操作，固化成一个技能，跑通整个流程——注册、检索、参数校验、执行、回归测试。把这个单点做扎实了，再往外扩。Agent的能力不是堆出来的，是一块砖一块砖砌出来的，而技能层就是那块最关键的砖。