最近我一直在重构一个内部用的 Agent 项目越改越发现一个问题模型的推理能力已经很强了但外面包的那层“手和脚”却乱成一团。有的工具函数散落在各个模块里有的技能逻辑写在 Prompt 里靠模型自觉发挥跑起来的结果完全不可控。后来我把整个系统按“技能”来做了一次彻底的重构效果提升非常明显。这篇文章就是围绕 agent-skills 这个思路来整理的把我踩过的坑、验证过的方案、可以直接抄的代码结构都放在这里。这个内容适合谁看如果你正在做 Agent 类应用不管是个人项目还是公司产品只要你遇到了“模型知道怎么做但执行经常出错”、“工具越加越多Agent 反而变笨”、“能力加了一堆但没法测试和复用”这类问题那这篇内容基本就是为你准备的。我会把技能系统从设计到落地的完整链路讲清楚包括为什么不能把技能塞进 Prompt、技能注册表的正确姿势、参数约束怎么做、Agent 如何自主选择技能、以及上线后怎么维护和排查问题。1. 为什么要把 Agent 的能力拆成“技能”先说一个很多人容易忽略的前提Agent 和普通的对话机器人不一样。普通机器人只需要“说得好”Agent 需要“做得到”。而“做得到”这件事靠模型背下来是不可靠的。模型记得住知识但记不住函数签名模型能理解意图但不一定能生成恰好兼容你业务系统的调用参数。1.1 从“一段话提示词”到“可调用的技能”早期做 Agent 的时候我习惯把所有能力都塞进系统提示词里比如“当你需要查天气时调用 weather_api 接口接口地址是 xxx参数是 city”。这种方式在测试阶段看起来没问题模型也确实会调用。但随着能力从三四个增加到十几个问题接踵而至模型开始混淆参数、忘记接口地址、甚至自己编造一个看起来很像但实际上不存在的函数名。后来我才意识到问题的本质提示词只适合描述语义不适合承载接口协议。真正可靠的做法是把每个能力封装成独立的、有明确输入输出约定的函数然后以结构化描述喂给模型——也就是常说的 function calling。这就是 agent-skills 这个设计思路的核心起点把“能力”变成“技能”每个技能有名字、有描述、有参数声明、有执行函数模型只负责根据用户意图选择合适的技能真正的执行逻辑全在代码里。这样做的好处非常直接。第一接口协议只维护一份不需要在提示词里反复抄写第二模型的选择空间被限定在可控范围内不会自己发明工具第三每个技能可以独立测试、独立升级出了问题能精确定位。这些都是把能力“技能化”之后才有的特性。1.2 技能、工具、工作流先厘清三者的边界在做技能化重构的时候我发现自己和团队花了不少时间在概念上打架。这里先明确我个人的定义不一定标准但后面所有内容都基于这套划分。工具Tool是最小可用单元比如“发送 HTTP 请求”“读取文件内容”“执行 SQL 查询”它不关心业务只做技术动作。技能Skill是面向业务场景封装的能力比如“查实时天气”“创建 Jira 工单”“从简历 PDF 中提取候选人信息”一个技能内部可能调用多个工具。工作流Workflow则是由多个技能按固定顺序组合成的完整流程比如“新人入职办理”需要先创建账号、再开通邮箱、再采购设备每个步骤都对应一个技能。这个分层非常关键。技能是中间这层它向上承接工作流的编排向下封装工具的细节。如果把工具直接暴露给模型模型会被大量非业务概念干扰如果只暴露工作流又太死板没法应对用户那千奇百怪的表达方式。技能的粒度刚好卡在“模型能理解”和“实现可复用”的最佳平衡点上。我见过不少团队在“技能粒度”上走极端。有一种是把技能切得特别碎比如把“发送邮件”拆成“配置SMTP”“构造邮件体”“调用发送接口”三个技能。模型面对这种碎到不能再碎的选择列表基本上就疯了它不知道为什么发送邮件要分三步经常只执行一半就停下。另一种极端是全揉成一个大函数参数列表几十个字段模型生成参数的时候错误率高得离谱。后面我会讲到我最后采用的技能设计原则基本能帮你绕过这两个坑。2. 技能如何设计才算合格注册、参数与调用约定技能化不是给函数“换个叫法”就完事它有一套自己的设计规范。这一节讲的是我验证过效果最好的技能设计方式从注册机制、参数声明到执行逻辑隔离每一步都附上为什么这么做。2.1 技能注册表让 Agent“知道”自己会什么技能注册表是整个技能系统的中枢。它要解决的问题是模型怎么知道自己可以调用什么调用条件是什么每个技能的能力边界在哪里我在实践中最推荐的注册表结构是“注册一个 JSON 描述列表”。每个技能注册项包含技能名称、自然语言描述、参数 JSON Schema、是否需要用户确认、以及回调执行函数。模型在每次请求时都会拿到这个列表根据用户意图从中挑选最合适的技能提取参数然后发出调用请求。这里有一个很关键的细节技能描述必须用“普适任务导向”的语言写而不是“具体实现”的语言写。举个反例如果你的描述是“调用 get_weather_v2 函数参数为 city_id 和 date”模型确实能调用但这个描述没有告诉模型“什么时候该用这个技能”。更糟糕的是一旦函数名改了或者版本升级了描述就得同步改很容易漏。正确的写法是“查询指定城市未来 7 天的天气信息适用于用户询问天气、出行建议、户外活动安排等场景”把“什么时候用”和“能做什么”说清楚函数名和实现细节交给注册表映射。另外一个我踩过的坑是不要把内部实现细节写进描述。有一次我为了调试把“该技能内部读取 Redis 缓存若缓存命中则直接返回”的描述也写进去了结果模型真的会在执行反馈里提到 Redis 缓存用户问“你怎么知道我要查的天气”模型回答“因为我读了 Redis”——这种无意义的信息会严重拉低用户体验和模型本身的判断准确率。2.2 参数 Schema技能的硬接口协议参数声明是整个技能系统里最不能偷懒的部分。模型能不能准确理解参数含义、能不能正确提取直接取决于你给的 JSON Schema 质量。我强烈建议必须用 JSON Schema 的完整语法把它当成前后端对接的 API 文档来写而不是粗略地列几个字段。一个合格的参数 Schema 要有这样几层信息参数类型string / integer / array / object 等、是否必填、字段含义描述、枚举值范围、格式约束、以及参数之间的依赖关系。以天气查询技能为例city 这个参数的描述不能只写“城市名”要写“用户提到的城市中文名或行政区划名例如北京、上海若用户只提供区级地名如朝阳区则补全为北京市朝阳区”这样的描述能把模型的解析准确率提升不少。Schema 里还有一个容易忽略的地方要声明参数的取值范围和格式。比如时间类的参数最好写明“格式为 YYYY-MM-DD”否则模型既可能输出“2024-01-01”也可能输出“2024年1月1日”甚至“明天”。我自己实际测试过不做格式约束的时候日期参数的解析成功率大概只有 70%加上明确格式约束和范围校验后基本能稳定在 98% 以上。有人会问参数那么多模型漏填怎么办我的经验是两类字段一定要区分开一类是模型必须从用户话里提取的“语义字段”比如“查上海明天下雨吗”里的城市和日期另一类是业务后台固定的“上下文字段”比如用户 ID、租户 ID、渠道来源。上下文字段不应该出现在模型输入的意图识别里而是在技能执行前由系统自动注入。这样能显著降低模型需要处理的参数数量准确率自然就上来了。2.3 技能实现业务逻辑必须与模型解耦这一点是 engineering 层面最重要的纪律技能的执行函数里绝对不能只丢一段“模型可能用到”的代码逻辑然后指望模型自己搞清楚怎么组合。技能实现必须做完整的参数校验、错误兜底、结果结构化。技能实现函数的通用骨架大致分为四步。第一步参数预检对模型传入的参数做运行时校验如果发现必填字段缺失或类型不对返回清晰可读的错误信息而不是直接抛出 Python 异常。第二步领域逻辑执行调用内部的工具函数完成任务。第三步结果格式化把执行结果整理成模型能看懂的结构化文本比如 JSON 字符串或 Markdown不建议返回一个 Python 对象因为模型在下一轮对话时需要以“文本形式”看到结果。第四步异常兜底捕获所有异常并转换为“技能执行失败 原因 可能的替代方案”三段式反馈。我着重强调一下结果格式化这一步。很多初学者会把接口原始响应直接返回给模型比如查天气的接口返回了含 500 多个字段的 JSON包含了气压、能见度、风速等一堆数据。模型看完这堆东西往往不知道该挑哪些重点告诉用户于是就会进行“自由创作”出现幻觉信息。正确做法是在技能实现里就完成后处理只返回最终面向用户的 3 到 5 句关键信息比如“上海明日小雨气温 24-28℃建议携带雨伞”。模型拿到这个干净的结果只需要做简单的转述或润色就行了幻觉空间被压缩到最小。3. 从零搭建一个 agent-skills 的最小闭环纸上谈兵谈完了这一节我们动手搭一个最小可运行的技能系统。我用了 Python 作为示例语言因为生态比较成熟实际上任何语言都可以核心架构思路是通用的。3.1 技术选型与目录结构我没有选用特别重的框架核心只依赖两样东西OpenAI 或其他兼容 function calling 协议的 SDK以及一个服务框架用于承载技能执行的 HTTP 接口。如果你用的是国内模型厂商的接口只要它支持 function calling 或 tool use 协议的思路完全一样。项目目录结构我建议按“技能即模块”的方式组织agent-skills/ ├── skills/ │ ├── __init__.py │ ├── registry.py # 技能注册表 │ ├── base.py # 技能基类与数据模型 │ ├── weather/ │ │ ├── __init__.py │ │ └── skill.py # 天气查询技能 │ ├── email/ │ │ ├── __init__.py │ │ └── skill.py # 邮件发送技能 │ └── calendar/ │ ├── __init__.py │ └── skill.py # 日程查询技能 ├── agent/ │ ├── orchestrator.py # Agent 主流程编排 │ └── prompt.py # 系统提示词管理 ├── tests/ │ └── test_skills.py # 技能单元测试 └── main.py # 启动入口这样组织的好处是每个技能都独立成包添加新技能不需要改动其他任何文件只需要在注册表里登记即可。对于后期技能超过 20 个的项目这种“插件化”结构能避免靠人肉修改一个巨型配置文件的灾难。3.2 实现技能注册与动态加载技能注册这块我推荐用“装饰器 元数据”的组合方式。这样做的好处是技能的定义、注册、声明三者集中在同一个 Python 文件中可维护性很高。先看技能基类的实现import json from typing import Callable, Optional, Any class Skill: name: str description: str parameters: dict {} required: list [] auto_confirm: bool False async def execute(self, **kwargs) - dict: raise NotImplementedError def to_tool_schema(self) - dict: schema { type: function, function: { name: self.name, description: self.description, parameters: { type: object, properties: self.parameters, required: self.required, }, }, } return schemato_tool_schema 方法很关键它会生成与 function calling 协议兼容的结构化描述模型侧看到的“工具列表”就来源于此。下面以天气技能为例展示完整实现class WeatherSkill(Skill): name query_weather description ( 查询指定城市当前或未来数日的天气情况 包括气温、降水概率、风力等信息。 适用于用户询问天气、出行准备、活动安排等场景。 ) parameters { city: { type: string, description: 用户提到的城市中文名例如北京、上海、广州。 }, date: { type: string, description: 查询日期格式为 YYYY-MM-DD默认当天。, }, } required [city] async def execute(self, **kwargs) - dict: city kwargs.get(city) date kwargs.get(date) # 这里接入真实天气 API或者在测试环境返回 mock 数据 result { city: city, date: date, condition: 小雨, temp_max: 28, temp_min: 24, advice: 建议携带雨伞, } return json.dumps(result, ensure_asciiFalse)注意 execute 返回的是 JSON 字符串不是 dict。我特意这样做的原因是模型在后续对话中接收到的是字符串形式的工具结果我们在技能层就把它转换成字符串可以避免编排框架在序列化时出现类型丢失或格式不一致的问题。技能注册表可以用一个简单的类来管理class SkillRegistry: def __init__(self): self._skills {} def register(self, skill: Skill): self._skills[skill.name] skill def get(self, name: str) - Optional[Skill]: return self._skills.get(name) def all_schemas(self) - list: return [skill.to_tool_schema() for skill in self._skills.values()] def names(self) - list: return list(self._skills.keys()) registry SkillRegistry() registry.register(WeatherSkill())上面这种全量注册已经能应对大多数场景。但项目技能数量增长到一定程度后我更推荐加入“按需注册”策略也就是不把所有技能一次性注册进去而是先通过一个召回器把可能相关的技能选出来再注册。这部分我会在后面“技能路由”那一节详细说明。3.3 让 Agent 自主选择技能并执行核心编排逻辑其实不复杂循环就三步把用户消息和工具描述发给模型模型返回调用指令或最终回复如果是指令则执行对应技能并把结果再喂回模型。下面是一段精简过的编排代码import asyncio from openai import AsyncOpenAI client AsyncOpenAI(api_keyyour-api-key) async def run_agent(user_message: str): messages [ {role: system, content: 你是一个能调用技能的智能助理。}, {role: user, content: user_message}, ] while True: response await client.chat.completions.create( modelgpt-4o, messagesmessages, toolsregistry.all_schemas(), tool_choiceauto, ) msg response.choices[0].message if msg.tool_calls is None: print(最终回复, msg.content) break messages.append(msg) for tool_call in msg.tool_calls: skill_name tool_call.function.name arguments json.loads(tool_call.function.arguments) skill registry.get(skill_name) if skill is None: result json.dumps({error: f未知技能: {skill_name}}) else: try: result await skill.execute(**arguments) except Exception as e: result json.dumps({error: str(e)}) messages.append({ role: tool, tool_call_id: tool_call.id, content: result, }) return messages[-1].content这段代码里有一个循环终止的保障点每当模型返回 tool_calls我们就执行技能并把结果以 tool 角色消息回填给它模型拿到结果后再次决策直到它认为信息足够、不再发起工具调用时才输出最终答复。这个循环天然能支持“多步调用”的场景比如用户说“上海周三会下雨吗如果下就帮我把周四的活动改成室内”模型可能会先查天气再查日程再改日程整个过程模型自己规划我们只需要在循环里提供标准化的执行环境。实测经验给 tool 角色的结果里带上 error 字段这个习惯特别重要。有一次模型连续调用了三次同一个失败技能就是因为我把异常吞掉并返回了一个空字符串模型认为没有结果继续重试。后来我改成固定返回error: 技能执行失败xxx模型会基于错误信息调整策略要么换技能要么直接向用户说明失败原因。4. 技能路由、组合与版本控制决定 Agent 上限的细节技能系统能跑通只是第一步。真正拉开差距的是技能多了之后你怎么让模型在几十个技能里还能保持高准确率以及新技能上线后怎么保证旧的用例不回归。4.1 让 Agent“选对”技能技能召回与意图优先技能数量一旦超过 15 到 20 个直接把全部技能描述塞给模型不是最优解。一方面模型的上下文窗口会被大量工具描述占掉真正留给对话历史和业务上下文的空间变少另一方面可选技能太多模型的选择准确率会显著下降。我测试过的一个典型数据技能数从 10 个增加到 30 个时模型在选择技能时的准确率会从 94% 降到 81% 左右这个下降对实际体验影响非常大。解决办法是在进入主模型之前加一个“技能召回”环节先用一个轻量级的匹配器从全量技能里筛出最可能相关的 5 到 8 个技能再把这些技能的描述注入给主模型。技能召回有几种做法从简单到复杂排序第一是基于关键词的倒排索引把技能描述里的核心名词建索引用户消息里有对应词就召回第二是基于 embedding 的向量检索把技能描述和用户消息都向量化后做相似度排序第三种是让一个小模型做分类选完技能后再交给大模型执行。我目前生产环境用的是向量检索加关键词兜底的组合方案召回率稳定在 97% 以上具体实现就不展开了属于可以全篇另写一篇的范畴。召回层还有一个很实用的收益它可以做技能的白名单和黑名单控制。比如企业内部场景某些技能只能给特定部门的人用召回层可以在这一步就把权限过滤掉避免模型把无权技能选出来。这个控制在纯“模型自主选择”的模式下几乎是做不到的因为模型并不理解组织架构和权限边界。4.2 技能的嵌套调用让技能内部能调用其他技能技能不仅应该被模型调用还应该能调用其他技能。这个看起来绕的设计其实能解决非常现实的问题。举个例子一个“创建会议”技能内部可能需要调用“查询参会人空闲时间”技能和“发送会议邀请”技能。如果把这些子步骤都暴露给顶层模型模型不仅要理解会议的语义还要编排多个技能的先后顺序出错概率高。更好的做法是把“创建会议”整个封装成一个复合技能内部编排调用链顶层模型只需要决定“要不要创建会议”以及“给哪些人创建”。复合技能的实现本质上就是在一个技能的 execute 方法内部持有注册表的引用然后调用其他技能的 execute 方法。我提醒一点复合技能内部调用可能产生循环依赖比如 A 调用 BB 又调用 A。我在设计初期没有加保护结果有一次线上出现了递归调用直到栈溢出的情况。现在我会在技能注册表中维护一个调用栈深度计数器深度超过 5 就强制熔断并返回“技能调用链过深”的错误。4.3 技能的版本与回归测试不回归是底线Agent 项目最怕什么最怕的是新版本模型上线后原来能通过的技能调用开始不稳定也怕重构技能实现后某个边缘场景被改挂了但没人发现。这两类问题靠人工验证是堵不住的必须靠自动化测试把行为锁定下来。我为技能系统设计了两种测试。第一种是纯单元测试不经过模型直接对技能的执行函数做参数校验和逻辑验证。比如给天气技能的 execute 传一个不存在的城市确认它返回的错误信息格式正确传一个非法的日期格式确认它返回格式错误而不是抛异常。这类测试跑得非常快每次提交代码都会被 CI 执行。第二种是基于黄金数据集的端到端测试。我会维护一组历史真实对话样本每一条都标注了“用户问题 期望调用的技能 期望的参数值”。这些样本会通过完整的 Agent 流程跑一遍然后断言模型选中的技能名和提取的参数是否符合标注。跑完一轮之后会产出一个准确率指标我用它来监控每次模型版本升级或技能描述调整对整体系统的影响。黄金数据集里的样本不是越多越好关键是覆盖每种技能的典型场景和边界场景目前我维护的大概 200 条左右跑一轮成本很低但带来信心非常足。做技能描述优化的核心推荐一次只改一个技能的描述然后跑一轮黄金测试集看指标变化。这个实验方法比同时改七八个技能之后凭感觉判断效果好得多能精确定位让指标下降的那次改动是哪里。5. 常见问题与排查技巧实录技能系统做了几个月之后我把遇到过的典型问题整理了一份速查表。这些问题几乎每个搭建 Agent 技能系统的人都会碰到分享出来帮你少走弯路。5.1 模型总是不调用技能而是自己“硬答”这是最经典的问题。你辛辛苦苦封装了技能模型却不按套路出牌用户问“查下北京的天气”模型愣是没有调用技能直接回答“北京今天天气不错哦”。排查方向其实是一个优先级问题。首先要检查技能描述是否足够清晰。如果描述写得太泛泛比如“提供天气相关的信息”模型根本判断不了这个技能是不是精确应对用户请求的很容易“宁可不调”。要把描述改成“查询指定城市天气必须通过该技能获取实时数据后才可回答”。第二个检查点是系统提示词不要给模型“你可以自由回答”的暗示要明确说“凡是涉及天气相关的问题需要调用工具获取实时信息后再回答”。第三个检查点是工具调用的返回模式确认 SDK 是否正确地传了 tools 参数很多人把 tools 传成 messages 的附加字段导致模型根本没接收到工具定义。5.2 技能执行报错Agent 就“摆烂”不继续了技能执行抛异常之后如果返回给模型的内容是乱糟糟的堆栈信息模型通常会出现两种反应一种是把堆栈原封不动复述给用户用户看到一堆无意义的英文报错另一种是假装无事发生直接生成一个编造的答案。两种都不可接受。我的处理方式是建立一套标准化的“错误语义协议”任何技能执行失败时必须返回三段式信息。第一段说明“发生了什么”比如“天气服务暂时不可用”第二段说明“为什么”比如“上游 API 返回了 503 状态码”第三段给出“替代方案”比如“建议稍后重试或尝试查询其他城市”。模型收到这个结构后会非常自然地生成对用户友好的回复甚至能主动给出建议动作。我还见过一种更极致的做法是在技能模块里实现降级逻辑比如查询天气的付费接口挂了就自动切换免费接口这种设计在可靠性要求高的场景里非常值得做。5.3 技能多了之后选择准确率明显下降这个问题在前面提到了主要是上下文被无关技能描述稀释导致的。我推荐的第一道防线就是技能召回机制把所有技能的描述压缩到必须的那几个。第二道防线是定期检查技能描述之间的“语义重叠”如果 A 技能描述里的关键词和 B 技能描述里的关键词大量重叠模型选错的概率就会高。我每新增一个技能都会先跑一遍所有技能描述做相似度分析相似度过高的两个技能会先做合并或者把其中一个的适用范围描述得更精确。检查工具方面直接用 embedding 计算两两相似度并不复杂把相似度超过 0.85 的技能对拎出来人工审查就行。另一个值得注意的问题是参数描述的质量。模型选对技能但提取错参数其实比选错技能更常见。比如预约会议技能用户说“约下周二下午三点”模型如果不知道今天星期几很容易把“下周二”解析错。解决思路有两种一种是在系统提示词里给模型注入当天的日期信息让模型在解析相对时间时有参照系另一种是技能参数里设计为只接收绝对时间相对时间的换算在技能执行前的“参数预处理”环节完成。6. 技能系统的扩展方向与维护心得最后说一点关于这个系统“以后还能怎么用”的个人体会。agent-skills 这套设计的最大价值是它把“让模型做一件事”变成“让模型从我们精心设计的技能库里选一件事来做”。这句话听起来简单但实际落地后的改变是巨大的。有一个我最近在做的扩展方向把技能的调用记录、参数分布、成功率、耗时这些指标全部打成日志做分析。这些数据用起来价值极高。比如你会惊讶地发现某一个技能在被模型调用的时候有 80% 的请求参数都是错的要么是模型理解能力不行要么是技能描述和参数 Schema 写得有歧义。这些数据反过来又能指导你优化技能的描述和参数约束形成正向循环。还有一个方向是技能从“被动调用”变成“主动建议”。以日程管理技能为例模型不一定非要等到用户明确要求才去查日程它可以在用户提到“明天下午开会”的时候自动查出当前日程中的冲突并提醒用户。这种主动行为必须在技能设计阶段就预留好触发条件和提示的边界不然容易变成“过度主动”反而让用户觉得烦。我现在再往后想技能系统完全可以沉淀成一套跨项目复用的“技能库资产”。这套资产和模型无关和业务场景有关。换了一个新模型只要它的 function calling 协议兼容技能注册表和执行层几乎不用改换了一个新场景只需要在技能库里新增技能复用已有的技能注册、召回、测试、监控体系。如果你准备长期做 Agent 方向那“技能资产化”这个概念越早建立越好。回头看我最初那个把能力散落在 Prompt 和零散函数里的版本现在这个按技能组织的系统无论是开发效率、测试覆盖还是线上稳定性都有质的提升。如果你也在搭自己的技能系统记住一条核心纪律先定好技能边界再做模型接入。技能边界先于模型能力做规划否则一旦技能定义混乱之后无论你的模型多聪明整套系统也很难立起来。