最近在搭建Agent应用的时候我反复踩到一个很隐蔽但杀伤力巨大的坑模型能力提升了工具也堆了一大堆但Agent就是无法稳定地解决稍微复杂一点的实际问题。后来我意识到问题不在于模型本身也不在于工具数量而在于我把工具的“能力”和“使用方式”混为一谈了。今天想好好聊聊agent-skills这件事也就是Agent的技能体系设计。先解释一下我理解的背景。现在的LLM应用已经过了单纯“接个大模型、套个提示词”的阶段稍微正经一点的Agent项目都会涉及工具调用、多轮规划、状态管理。但工具多了之后最大的痛点变成了模型根本不知道怎么选工具即使选对了参数也经常填错即使参数填对了用的方式也很粗糙完全谈不上“技能”。而agent-skills这个概念核心就是把“工具”进一步包装成“技能”不仅告诉模型有什么还告诉它什么时候用、怎么用、出错怎么办。这篇文章会从技能体系的设计思路、核心接口规范、实际实现路径到线上问题排查完整过一遍。不管你是刚接触Agent开发的爱好者还是已经在生产环境里和工具调用搏斗过的工程师这篇内容应该都能给你一些新的启发。1. agent-skills到底在解决什么问题1.1 为什么Agent不能只有一个大脑很多人一开始做Agent的时候思路很简单把大模型当作大脑给它一堆函数定义让它自己选着调。这个思路在小Demo里跑得很溜但一旦进入真实业务场景立刻会遇到几个连锁问题。第一个问题是上下文膨胀。每个工具的定义尤其是有复杂参数结构的函数会占用大量的token。你把20个工具塞给模型还没有开始干活光描述这些工具就已经花掉几千token了而且随着工具越来越多模型理解这些工具的难度也越来越大。我把这个过程类比成让一个新人同时看50页说明书再让他干活——他大概率是懵的。第二个问题是决策质量下降。模型在大量同质化的工具面前选择准确率会明显下降。举个例子你有“查天气”和“查空气质量”两个工具接口长得非常像参数里都有城市名。模型经常搞混调错了又不是报错它只是返回了用户并不需要的信息。用户觉得不智能但实际上问题出在工具设计上。第三个问题是行为不可控。没有技能化封装的工具模型的调用方式千奇百怪。同一个功能它今天传字符串明天传对象后天干脆自说自话编一个工具。没有一套统一的技能壳你就很难做约束、审计和故障隔离。agent-skills的思路相当于从“给模型一堆零件”升级为“给模型一套带说明书的专用工具”。每个技能都包含清晰的触发条件、依赖关系、使用步骤和异常处理策略。它不是一个工具而是一整套“在什么场景下如何完成一类任务”的规则包。1.2 Agent Skills和Function Calling的关系很多文章会把Agent Skills和Function Calling混为一谈但实际上它们是两个层面的东西。Function Calling是模型底层的API能力它让模型能够输出结构化的函数调用请求而Agent Skills是应用层的一种设计模式它决定你如何组织工具、如何引导模型正确地调用工具。我的理解是这样的Function Calling是“手”Agent Skills是“大脑的训练手册”。没有Function Calling模型没法把手伸到外部世界没有Agent Skills手就会乱摸。我实际开发中的感受是直接把所有能力都挂到Function Calling下面就是把所有工具都平铺在一个列表里。而Agent Skills框架会在Function Calling之上增加一层逻辑例如技能路由、参数预处理、结果后处理、失败兜底。这就像给每个工具配备了一位“值班经理”它负责判断现在该不该上这个工具参数怎么填最合理出了问题该怎么补救。另外还有一个重要区别Function Calling基本都是模型自己直接生成的调用但Agent Skills可以先经过一层“规划器”决定调用链再由模型填充参数。这种设计对复杂任务非常有用因为复杂任务往往需要多个工具按顺序配合而不是一次调用就能搞定。2. 一套可用的技能体系应该怎么设计2.1 技能接口设计的核心要素如果你打算自己搭建一套技能体系第一个要解决的问题是一个技能到底长什么样我建议至少包含元信息、输入描述、执行逻辑、输出规范和异常处理这五个部分。元信息是最基本的包括技能名称、版本号、所属领域、标签等等。别小看这些字段它们在技能路由和权限管理时非常重要。我见过的很多翻车现场都是因为技能没有版本号算法团队悄悄改了一个功能结果给用户返回了完全没预期的结果线上查半天都查不到原因。输入描述不能简单给一个JSON Schema就完事还要在后面写上“参数示例”和“参数约束”。比如同样是一个日期参数你要说清楚格式是YYYY-MM-DD还是时间戳如果用户输入的是“明天”这种相对时间技能内部要不要做自然语言解析。这些直接影响模型的填充准确率。执行逻辑表达的是“进入这个技能之后做什么”它可能是一段代码、一个API调用甚至是一串协调多个内部服务的子技能。这里的关键是逻辑要尽量原子化一个技能只干一类事不要搞那种一进去就判断A又判断B的缝合怪。输出规范也很关键如果你这个技能的输出会被下一个技能作为输入那你必须在设计阶段就规定好输出的数据结构和样例。否则模型在中间做转换时会自己发挥常常产出一些不伦不类的格式。最后是异常处理。技能执行不可能100%成功外部API会挂、网络会抖动、数据会缺失。一个好的技能设计至少要为每一种常见异常给出兜底答案或者降级方案而不是直接把一个“Internal Server Error”丢给模型去“反思”。2.2 技能描述怎么写模型才不走偏写好技能描述真的是一门玄学但它其实是有方法论的。我总结出的核心原则就一条描述是用来给模型做决策的不是用来给程序员写文档的。什么意思呢程序员写文档喜欢将心比心把内部实现细节都写得很清楚。但模型选技能的时候它需要的不是“这个函数用了什么排序算法”而是“这个技能适合处理什么请求、不适合处理什么请求、调用时要注意什么”。我举一个正面例子。“查询订单物流”这个技能差的描述是“查询订单物流信息参数为订单编号。”好的描述是“当用户想了解已下单商品的配送进度时使用此技能。需要传入订单号订单号一般在用户的订单列表中可以找到。如果用户没有提供订单号请先引导用户提供订单号再进行查询。”看到区别了吗差的描述只说了功能好的描述给出了触发时机、前置条件、以及缺失参数时的处理方式。还有一点很重要就是一定要写清楚“不适用场景”。很多模型调用错误就是因为它分不清两个相似技能。你在描述里加一句“本技能不适用于查询线下门店库存如有此需求请使用XXX技能”能非常有效地减少错误路由。这种负向约束是我用过最有效的调优手段之一。再补充一个小技巧把技能的典型场景用自然语言写成一两个例句模型对例子的敏感度远高于对抽象定义的敏感度。比如“当用户说‘我的快递到哪了’时优先使用本技能”这句话比写10行逻辑描述都管用。2.3 技能发现与动态加载机制当技能数量上到几十上百个的时候另一个问题就凸显出来了你不能把所有技能的定义一次性全部塞给模型成本太高而且噪声太大。这时候就需要技能发现机制。我目前用得最顺手的方案是“注册中心 两级索引”。所有技能启动时注册到一个技能中心技能中心维护一个倒排索引根据关键词、领域、历史调用频次等维度在每次Agent请求到来时先做一次粗筛把候选技能缩小到5到10个然后再把这个小集合的描述喂给模型做精确选择。为什么不能只靠模型选因为模型的能力再强面对100个技能定义也会“走神”。粗筛这步相当于给模型做了一次预筛选范围小了准确率自然就上去了。这就像你让一个人去图书馆找书你直接把书放到书架上分类标签清楚了他找起来就快得多。动态加载也很重要。我偏好用懒加载的模式而不是应用启动时一次性全部加载。技能升级了替换注册中心里的定义即可新请求进来自动用新版本某技能被熔断了直接从候选列表里摘掉。有了这一步整套系统的运维成本能降低一个量级不用每次改技能都发版上线。2.4 技能目录与依赖管理技能多了以后你会自然面临一个“依赖地狱”的问题。技能A内部要调用技能B技能B又依赖技能C。如果你在错误处理时没有一套依赖管理逻辑很容易形成循环调用或者在一个技能失败时引发连锁崩溃。我的做法是给每个技能在元信息里加上“依赖清单”声明这个技能运行需要哪些其他技能、需要哪些外部权限。然后在技能启动时做一个依赖检查发现有环就直接报错有缺失就提示注册。这有点像传统软件开发里的依赖注入只不过在Agent场景下这个检查要动态做因为技能是可以热插拔的。还有一个很现实的建议不要让子技能直接暴露给模型应该由父技能内部去编排子技能的调用。换句话说模型只看到“数据分析”这一个技能至于这个技能内部是先做数据清洗还是先做格式转换模型不需要关心。这样既减少了模型的决策压力也把执行路径封装成了一个稳定接口出问题时也好排查。3. 从零实现一个技能模块的完整过程3.1 技能项目的目录结构与脚手架理论说了一堆还是得落到代码上。假设你准备用Python来实现我推荐一个比较标准的技能项目结构skills/ ├── __init__.py ├── base.py # 技能基类定义抽象接口 ├── registry.py # 技能注册中心 ├── loader.py # 技能动态加载器 └── builtin/ ├── __init__.py ├── weather_check.py # 一个示例技能天气查询 ├── order_query.py # 另一个示例技能订单查询 └── ...base.py 这个文件是整个体系的骨架它定义了所有技能必须实现的接口。我的习惯是这个基类包含name、description、parameters、dependencies这样的类属性以及execute()、validate()、fallback()这样的实例方法。每个子技能只需要关注自己的业务逻辑公共的鉴权、日志、监控都在基类里完成。loader.py 做的事情很粗暴就是扫描指定目录下的所有.py文件把继承基类的子类都找出来并实例化然后注册到registry里。如果你用的是Java或者TypeScript也可以用反射机制或者装饰器思路是完全一样的。3.2 技能基类的接口设计实践写基类的时候我特别强调“参数校验”和“错误分类”。光是在基类里定义好接口还不够你得把“参数校验失败”和“业务执行失败”和“外部依赖失败”区分开这样后面做重试和兜底才能有的放矢。下面是一个简化的基类参考实现Python伪代码from abc import ABC, abstractmethod from enum import Enum class SkillErrorType(Enum): PARAM_INVALID param_invalid EXECUTION_ERROR execution_error DEPENDENCY_ERROR dependency_error class BaseSkill(ABC): name: str description: str parameters: dict {} dependencies: list [] abstractmethod def validate(self, params: dict) - dict: 解析并校验输入参数返回规范化后的参数 pass abstractmethod def execute(self, params: dict, context: dict) - dict: 执行技能核心逻辑返回结构化结果 pass def fallback(self, error_type: SkillErrorType, params: dict) - dict: 异常兜底逻辑决定返回给模型什么信息 return { success: False, error_type: error_type.value, message: 技能执行失败请稍后重试 }可以看到validate和execute是完全分离的。这样做的好处是参数问题可以尽早拦截不用真的跑到外部API那里才发现参数不对。fallback单独抽出来也很重要因为我发现如果让每个技能自己随便写失败逻辑最后返回给模型的错误信息五花八门模型根本没法理解自然也就没法做下一步决策。3.3 一个具体技能的实现天气查询Demo理论讲完用一个最简单的“天气查询”来做示例因为这个技能每个人都能看懂。class WeatherCheckSkill(BaseSkill): name weather_check description ( 当用户询问某个城市当前的天气、气温、降水概率等气象信息时使用。 需要传入城市名如果城市名不明确请结合用户IP或历史记录判断。 本技能不支持查询历史天气如需历史天气请使用weather_history技能。 ) parameters { type: object, properties: { city: { type: string, description: 城市名称如北京、上海、广州 } }, required: [city] } def validate(self, params): city params.get(city) if not city: raise SkillParamException(缺少城市参数) # 这里可以做城市名规范化比如“帝都”转成“北京” return {city: normalize_city(city)} def execute(self, params, context): city params[city] # 调用天气服务商API这里省略具体实现 weather_data weather_api.fetch(city) return { success: True, city: city, temperature: weather_data[temp], condition: weather_data[condition] }这段代码本身不难但有几个细节值得展开说。description中的“不支持查询历史天气”这句话非常关键。这能最大程度减少模型把相关任务误派给这个技能的概率。我在实际测试中发现加入这种负向描述后错误路由率能下降30%以上。validate中做城市名规范化也很重要。用户不会老老实实输入“北京”他可能说“帝都”“Beijing”“北京市”。技能层把这种归一化逻辑做掉模型填充参数的负担就小了。我见过很多Agent项目把归一化逻辑放在提示词里结果每次都要加一堆“不要输出缩写”的规则效果还不好。把这种确定性的逻辑放到代码里永远比让模型做更可靠。3.4 技能注册中心的实现逻辑说完了单个技能再看技能注册中心。它的核心职责是维护技能清单、提供粗筛能力、管理技能生命周期。我写过一个极简版本核心逻辑大概只有几十行。class SkillRegistry: def __init__(self): self._skills {} def register(self, skill: BaseSkill): self._skills[skill.name] skill def search(self, query: str, top_k: int 5): # 用关键词对技能描述做倒排打分 scores {} for name, skill in self._skills.items(): score 0 for token in query.split(): if token in skill.description: score 1 scores[name] score ranked sorted(scores.items(), keylambda x: x[1], reverseTrue) return [self._skills[name] for name, _ in ranked[:top_k]]这个实现虽然粗糙但已经能完成“粗筛”的核心工作了。你完全可以把它换成向量检索、基于历史调用的协同过滤或者其他更聪明的方法。但我觉得新手一开始不需要整得太复杂先跑通流程再慢慢优化检索效果。注意一点search这一步是在把候选集喂给大模型之前做的它的目的是降噪不是做最终决策。最终决策还是要靠大模型根据候选技能的描述来选。所以这里不需要追求100%的准确率召回做得好就够了。3.5 模型路由到技能调用的完整链路技能都准备好之后一个完整的调用链路长什么样以我常用的LangChain框架为例其他框架思路类似from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-4o-mini, temperature0) # 从注册中心粗筛出候选技能然后转换成LangChain的Tool对象 candidate_skills registry.search(user_query, top_k5) tools [skill_to_tool(skill) for skill in candidate_skills] agent create_tool_calling_agent(llm, tools) executor AgentExecutor(agentagent, toolstools) result executor.invoke({input: user_query})在这个过程中有一个非常值得注意的点temperature一定要设成0至少在技能选择阶段要设成0。技能路由是一个确定性任务你不需要模型发挥创造力你只需要它稳定选择正确的技能。我见过好几个人在Agent里用了默认温度然后模型每次选的工具都不一样最后线上表现忽好忽坏查了半天才发现是这个原因。另外在整条链路里建议加一个“技能执行结果反馈解析模块”它负责把技能的原始返回结果转换成模型容易理解的语言。比如气温模块返回的是{temperature: 23.5}反馈解析模块会把它拼成“北京当前温度为23.5摄氏度”然后再返回给模型。这样模型就不需要自己去读奇怪的JSON结构最后回答用户时也更自然。4. 真实环境里的坑与排查方法4.1 “模型选错技能”的常见根因如果你发现模型经常选错技能不要急着怪模型先检查自己的技能定义。我总结下来有三个高频原因。第一个原因是技能描述太抽象——通篇讲功能不讲触发场景。比如“本技能用于计算两个日期之间的天数”模型可能看不出来这个技能其实可以回答“我离职倒计时还有多少天”。好的描述应该明确写出能被自然语言触发的方式把用户的各种问法都尽可能概括进去。第二个原因是相似技能之间没有做差异化说明。如果你有两个技能一个是“查国内天气”另一个是“查国外天气”接口参数都一样模型很容易搞混。这时候你就需要在描述里主动写清楚边界甚至可以互相引用“如果用户问的是中国境内城市不要走本技能请用国内天气查询技能。”第三个原因不是描述问题而是粗筛阶段把正确技能过滤掉了。我在系统里把粗筛出的候选数设成top_k3结果用户问的是历史天气但历史天气技能排在第4位模型根本没有机会选到它。后面我调整了粗筛算法把候选数调到8个终身搞定的问题突然就好了。所以排查的时候先确认候选集里到底有没有正确技能再谈模型傻不傻。4.2 参数解析失败的几种典型场景技能调用中参数解析是翻车重灾区。我整理过自己线上报错日志发现主要就是三个问题。第一个是时间类参数格式混乱。用户说“周三下午三点”模型如果直接把这个字符串塞给技能技能内部的API是肯定不认的。所以我提倡在技能内部做一个专门的时间解析函数支持“明天”“下周一”“X分钟后”这类自然语言相对时间。如果只有少数几个技能涉及放在技能内部处理即可如果到处都是时间参数建议抽成一个公共的时间处理模块。第二个是枚举参数超界。你给技能定义了order_status可选值是pending、shipped、completed但模型可能传一个received进来。这其实是你的参数描述不够清晰没有把可选项完整列出来。解决方法是参数描述里不仅列出可选项还要解释每个选项的业务含义适当的给一个示例参数值模型理解后就能输出正确值。第三个是隐式上下文缺失。例如用户说“帮我订张这周五去上海的票”没有明说出发地。技能校验时发现缺少出发地正确的做法是通过技能内部逻辑获取上下文里的默认城市或者向用户主动追问而不是直接把参数错误丢回给模型。把追问之类的兜底逻辑写在技能里会让整条链路体验好很多。4.3 多个技能叠加时的并发与冲突处理当两个技能都希望修改同一个资源时冲突就不可避免。比如一个技能要写订单备注另一个技能要改订单地址如果并发执行后写的会把先写的覆盖掉。这里我坚持的原则是尽量让一个完整任务走单一的父技能不要多个技能各自为战。如果架构上确实不可避免并行调用多个技能那要引入锁或者版本号机制。最简单的一种做法是技能执行前读取资源版本号执行完成提交时带上版本号如果发现版本号已被其他技能更新则任务失败并触发重新规划。这就像经典软件工程里的Compare And Swap看着古老但在Agent场景下非常实用。还有一个调度层面的建议技能路由决定后多个独立技能可以并行执行但写在依赖清单里的技能一定要严格串行。我有一个项目踩过这个坑技能A需要技能B的结果代码里却让两个线程同时跑结果A拿到的永远是空数据白白浪费了好几天排查时间。4.4 排查技能问题的实用技巧最后分享几个排查技能问题的小技巧都是我实际用下来觉得效率很高的方法。一个是“技能调用日志必须全链路追踪”。从用户输入到粗筛结果到模型选择的技能名到技能校验后的参数到执行返回每一步都打点。你现在看觉得简单但很多Agent项目上线时连“模型到底选择了哪个工具”都没有日志一出问题就只能抓瞎。只要把每一步记录下来很多时候问题一眼就能定位。另一个是“离线回放机制”。我会把线上用户请求和当时的技能调用结果全部保存下来形成一个回放数据集。每次修改技能定义或路由策略后先不直接发线上而是在离线环境里跑一遍历史数据看技能选择准确率和参数合法率有没有变差。这套机制救过我很多次因为改描述、改参数schema很容易修好评测集却让真实场景下崩掉。再一个是用好“人工测试脚本”。我强烈建议你为每个技能写一个独立的测试入口可以直接用命令行触发绕过模型直接调用技能的validate和execute。这样做有两个好处一是开发时快速调通技能本身的逻辑不用每次都要拼装整个Agent二是出问题时可以快速区分到底技能本身有bug还是模型调用方式不对。很多Agent框架本身不带这种测试能力自己写一个也不麻烦但收益巨大。还有一个很多人忽略的点技能内部一定不要裸奔要把超时控制加上。外部API延迟模型会一直傻等最终导致完整响应超时。我做了一个“超时兜底”机制技能里所有外部调用都包一层超时超时后直接走fallback返回一个提示信息给模型模型再去选择要不要换一个技能或者直接告诉用户稍后再试。这个细节在线上非常管用。说实话把agent-skills这套体系从无到有搭起来最开始只是为了解一个“工具太多模型不会用”的问题。但做到后面我发现它本质上做的是“把人的业务经验结构化成模型可执行的规则”这个价值远大于单纯地优化一次工具调用。最后再说一个我真实踩过坑后的强烈建议技能的description和异常处理一定要当成一等公民来对待不要等上线后出问题了再回头补。我第一版技能系统上线时把所有精力都花在“让技能跑通”上结果用户问了一个稍微偏门的问题模型就开始胡说八道调用了完全不搭边的技能。后来我把每个技能的描述按“触发时机 正反例 不适用场景”三要素重写了一遍整体效果提升非常显著而且几乎没有引入任何新的模型能力成本。这一条我觉得值得你在自己的Agent项目里优先验证一下。