1. 从agent-skills这个标题说起它到底在解决什么问题第一次看到agent-skills这个项目标题我的直觉是这大概率是一个围绕智能体能力封装、复用与编排的工程化项目。为什么这么判断因为agent这个词在过去两年里已经从学术论文里的抽象概念变成了工程落地中的具体模块而skills这个词则直接指向了能力——不是模型本身的能力而是模型之外、可以被调用、被组合、被版本管理的那一层能力。说白了大模型本身是个通才但通才不等于专家。你让它写首诗、编个故事它信手拈来但你让它去查一下某个内部系统的库存、按公司规范生成一份周报、或者调用某个特定API完成一次数据同步它就开始抓瞎了。原因很简单模型的知识截止于训练数据它的行动能力受限于它被赋予的工具。而agent-skills要做的就是把这层工具流程约束打包成一个个可插拔的技能模块让智能体在需要的时候按需加载、按需执行。这个项目适合谁来参考我梳理了三类人。第一类是正在做智能体应用开发的工程师你们可能已经踩过每个业务场景都从头写一遍工具调用逻辑的坑这个项目能帮你把重复劳动抽象掉。第二类是对智能体架构感兴趣的产品经理或技术负责人你们需要理解技能这个抽象层到底怎么设计、边界在哪里。第三类是刚入门AI应用开发的新手你们可以从这个项目里看到一个完整的、可运行的技能编排范式而不是停留在调个API就完事的层面。我个人的判断是agent-skills这类项目的核心价值不在于它实现了多少个技能而在于它定义了一套技能如何被描述、被发现、被调用、被组合的协议。这套协议才是真正能沉淀下来的东西。接下来我会从设计思路、核心细节、实操过程、问题排查四个维度把这个项目拆开揉碎讲清楚。2. 整体设计与思路拆解为什么是技能而不是工具2.1 从工具调用到技能封装的认知升级早期做智能体应用大家的做法很直接给模型一个工具列表每个工具就是一个函数模型根据用户意图选择调用哪个函数。这种做法在工具数量少的时候没问题一旦工具数量超过十个模型的选择准确率就会明显下降。我实测过一个场景当工具数量从5个增加到20个时模型选错工具的概率从不到5%飙升到接近30%。这不是模型不行而是扁平化的工具列表本身就不符合人类解决问题的认知模式。人类专家解决问题时脑子里不是装着一个几百项的工具清单而是装着若干个技能包。比如一个运维专家他的技能包里可能有排查服务异常、扩容集群、回滚版本这几个高阶技能每个技能内部又包含若干具体操作。当他面对一个问题时先匹配技能包再在技能包内部细化操作。这种分层匹配的策略才是agent-skills这类项目要复现的核心思路。所以这个项目的第一个设计决策就是把技能作为一等公民而不是把工具作为一等公民。技能是对工具的封装一个技能可以包含多个工具调用、多个条件分支、多个后处理步骤。这样做的好处是模型只需要在技能这一层做选择选择空间被大幅压缩准确率自然就上去了。2.2 技能描述协议的设计考量技能要被模型理解和调用就必须有一套描述协议。这套协议要回答几个问题这个技能是干什么的什么时候该用它用它需要提供什么参数它会返回什么执行过程中有哪些约束我见过不少项目在这块偷懒直接把函数的docstring扔给模型。这种做法能用但不够好。原因是docstring是写给程序员看的不是写给模型看的。模型需要的是意图匹配层面的描述而不是参数类型层面的描述。举个例子一个查询天气的工具docstring可能写的是get_weather(city: str) - dict但模型需要的是当用户询问某个城市的天气状况、温度、是否下雨时使用此技能需要提供城市名称。agent-skills在这块的设计思路是技能描述采用意图约束示例的三段式结构。意图说明这个技能解决什么问题约束说明使用时的前置条件和边界示例给出几个典型的调用场景。这种结构的好处是模型在做技能选择时可以同时参考语义匹配和示例匹配准确率比单纯依赖意图描述要高出一截。2.3 技能加载与执行的分离设计另一个值得说的设计决策是技能的加载和执行是分离的。加载阶段只负责把技能的元信息描述、参数schema、依赖关系注册到智能体的技能池里执行阶段才真正去调用底层工具。这种分离带来的好处是智能体可以在不执行任何实际操作的情况下先知道自己有哪些技能可用从而在规划阶段就做出更合理的决策。我打个比方这就像你去一家餐厅吃饭菜单是加载阶段你看着菜单决定点什么厨房做菜是执行阶段你点完之后厨师才开始干活。如果菜单和厨房混在一起你每看一道菜厨师就做一道那效率就太低了。分离设计让智能体可以先看全菜单再下单规划质量会明显提升。2.4 为什么选择这种架构而不是其他方案市面上做智能体能力扩展的方案不止一种。有的方案走的是微调路线把能力直接训进模型里有的方案走的是提示词工程路线靠复杂的prompt来引导模型还有的方案走的是工作流编排路线把整个流程固定死。agent-skills选择的是技能插件化路线我认为这个选择是合理的。微调路线成本高、迭代慢而且一旦模型更新之前微调的能力可能就失效了。提示词工程路线灵活但脆弱prompt稍微改几个字模型的行为就可能跑偏。工作流编排路线稳定但僵化无法应对开放式的用户请求。技能插件化路线在灵活性和稳定性之间取了一个平衡点技能本身是稳定的、可测试的但技能的选择和组合是动态的、由模型决定的。3. 核心细节解析与实操要点技能模块的解剖3.1 技能定义文件的结构一个技能的定义文件通常包含以下几个部分技能标识、技能描述、参数schema、执行逻辑、依赖声明、以及可选的示例。我用一个虚构的查询库存技能来举例说明。skill_id: query_inventory description: 当用户询问某个商品的库存数量、是否缺货、补货时间时使用此技能 parameters: - name: product_name type: string required: true description: 商品名称支持模糊匹配 - name: warehouse type: string required: false description: 指定仓库名称不填则查询所有仓库 constraints: - 商品名称不能为空 - 单次查询最多返回50条记录 examples: - input: 查一下A商品的库存 output: A商品在华东仓有120件华南仓有80件 - input: B商品缺货吗 output: B商品当前总库存为0预计3天后补货这个结构里description是给模型做意图匹配用的parameters是给模型做参数填充用的constraints是给执行层做校验用的examples是给模型做少样本学习用的。四者缺一不可。注意description的写法非常关键。我踩过的坑是早期把description写得太技术化比如调用库存数据库查询接口结果模型经常在用户问这个商品还有货吗的时候不触发这个技能。后来改成当用户询问商品库存、缺货、补货相关问题时使用触发率立刻上来了。description要写用户意图不要写技术实现。3.2 参数schema的设计陷阱参数schema看起来简单实际上坑很多。最常见的坑是参数类型过于严格。比如你把warehouse参数定义成枚举类型只允许华东仓、华南仓、华北仓三个值。但用户可能说上海仓、广州仓模型在填充参数时就会失败。我的经验是对于面向用户的参数尽量用string类型加模糊匹配把严格的校验放到执行层去做。执行层拿到上海仓之后可以通过别名映射表把它转换成华东仓。这样模型不用背仓库别名执行层也不用担心模型填错。另一个坑是必填参数过多。如果一个技能需要用户提供五个必填参数模型大概率会漏填或者瞎填。我的做法是必填参数不超过两个其余的都设成可选执行层根据可选参数的缺失情况做降级处理。比如查询库存时product_name必填warehouse可选不填就查全部。3.3 技能执行逻辑的编写要点执行逻辑是技能真正干活的地方。这块的编写要点有三个幂等性、超时控制、错误封装。幂等性是指同一个技能用同样的参数调用多次结果应该是一致的。这对于查询类技能天然满足但对于写入类技能就需要特别注意。比如一个创建工单的技能如果模型因为某种原因重复调用了两次就会创建两个重复工单。解决办法是在执行逻辑里加去重判断或者引入幂等键。超时控制是指技能执行不能无限期挂起。我建议每个技能都设置一个超时时间查询类技能5秒写入类技能15秒复杂计算类技能30秒。超时之后返回一个明确的错误信息让模型知道这个技能暂时不可用而不是一直等下去。错误封装是指技能执行失败时返回给模型的错误信息要模型友好。不要把原始的堆栈信息扔给模型那样模型看不懂。要把错误转换成自然语言描述比如库存系统当前不可用请稍后重试或者未找到名为XXX的商品请确认商品名称是否正确。3.4 技能之间的依赖与组合单个技能能解决的问题有限真正有价值的是技能的组合。比如生成月度销售报告这个任务可能需要依次调用查询销售数据、计算同比环比、生成图表、导出PDF四个技能。agent-skills处理技能组合的方式是允许技能声明自己的前置依赖和后置产出。前置依赖说明这个技能需要哪些数据作为输入后置产出说明这个技能会生成哪些数据。智能体在规划时可以根据依赖关系自动编排技能的执行顺序。这块的实操要点是依赖声明要尽量细粒度。不要说需要销售数据而要说需要指定月份的销售明细列表。细粒度的依赖声明让智能体更容易找到匹配的上游技能。4. 实操过程与核心环节实现从零搭建一个技能4.1 环境准备与项目初始化假设我们要从零搭建一个基于agent-skills范式的智能体应用第一步是环境准备。我推荐的技术栈是Python 3.10以上版本配合一个轻量的Web框架比如FastAPI来暴露技能接口用一个向量数据库比如Chroma或FAISS来做技能描述的语义检索。为什么需要向量数据库因为当技能数量超过50个时把所有技能描述塞进prompt里会超出上下文窗口。用向量数据库做一次粗筛只把最相关的10个技能描述塞进prompt既节省token又提升准确率。项目初始化的目录结构我建议这样组织agent-skills-demo/ skills/ __init__.py query_inventory.py create_ticket.py generate_report.py registry/ skill_registry.py vector_store.py executor/ skill_executor.py error_handler.py config/ settings.yaml main.pyskills目录放各个技能的实现registry目录放技能注册和检索逻辑executor目录放技能执行和错误处理逻辑config放配置文件。4.2 技能注册流程的实现技能注册的核心逻辑是扫描skills目录下的所有技能定义解析元信息写入技能注册表同时把技能描述向量化后存入向量数据库。import importlib import os from registry.vector_store import VectorStore class SkillRegistry: def __init__(self, skills_dir, vector_store): self.skills_dir skills_dir self.vector_store vector_store self.skills {} def register_all(self): for filename in os.listdir(self.skills_dir): if filename.endswith(.py) and not filename.startswith(__): module_name filename[:-3] module importlib.import_module(fskills.{module_name}) skill_def module.SKILL_DEFINITION self.skills[skill_def[skill_id]] skill_def self.vector_store.add( skill_def[skill_id], skill_def[description] ) print(f已注册 {len(self.skills)} 个技能)这段代码的关键点是技能定义以模块级变量SKILL_DEFINITION的形式暴露注册器通过动态导入的方式加载。这样做的好处是新增技能只需要在skills目录下加一个文件不需要修改注册器的代码。4.3 技能检索与选择的实现技能检索分两步先用向量检索做粗筛再用模型做精排。def select_skills(self, user_query, top_k10): candidates self.vector_store.search(user_query, top_ktop_k) candidate_descriptions [] for skill_id in candidates: skill self.skills[skill_id] candidate_descriptions.append( f技能ID: {skill_id}\n描述: {skill[description]}\n f参数: {skill[parameters]}\n示例: {skill.get(examples, [])} ) prompt f用户请求{user_query}\n\n可选技能\n \n---\n.join(candidate_descriptions) prompt \n\n请选择最合适的技能并给出调用参数。如果不需要任何技能返回NONE。 response call_llm(prompt) return parse_skill_selection(response)这里的top_k我建议设成10到15之间。设太小可能漏掉相关技能设太大又浪费token。实测下来10是一个比较平衡的值。4.4 技能执行的完整链路技能执行的完整链路是解析模型返回的技能选择结果 - 校验参数 - 执行技能 - 封装结果 - 返回给模型。def execute_skill(self, skill_id, params): if skill_id not in self.skills: return {error: f技能 {skill_id} 不存在} skill self.skills[skill_id] validation_error self.validate_params(skill, params) if validation_error: return {error: validation_error} try: result skill[handler](**params) return {result: result} except TimeoutError: return {error: 技能执行超时请稍后重试} except Exception as e: return {error: f技能执行失败{str(e)}}参数校验这块我建议做两层第一层是类型校验检查参数类型是否匹配第二层是业务校验检查参数值是否在合理范围内。类型校验可以用pydantic自动完成业务校验需要手写。4.5 一个完整案例库存查询技能的实现我把库存查询技能的完整实现写出来方便你直接参考。SKILL_DEFINITION { skill_id: query_inventory, description: 当用户询问某个商品的库存数量、是否缺货、补货时间时使用此技能, parameters: [ {name: product_name, type: string, required: True, description: 商品名称支持模糊匹配}, {name: warehouse, type: string, required: False, description: 指定仓库名称不填则查询所有仓库} ], constraints: [ 商品名称不能为空, 单次查询最多返回50条记录 ], examples: [ {input: 查一下A商品的库存, output: A商品在华东仓有120件}, {input: B商品缺货吗, output: B商品当前总库存为0} ], handler: None } def query_inventory_handler(product_name, warehouseNone): if not product_name: raise ValueError(商品名称不能为空) results db.query_inventory(product_name, warehouse) if len(results) 50: results results[:50] if not results: return f未找到名为{product_name}的商品 summary [] for r in results: summary.append(f{r[warehouse]}有{r[quantity]}件) return f{product_name}的库存情况 .join(summary) SKILL_DEFINITION[handler] query_inventory_handler这个实现里handler函数是真正干活的SKILL_DEFINITION是给注册器用的。两者放在同一个文件里维护起来比较方便。5. 常见问题与排查技巧实录踩过的坑和填过的土5.1 技能选择准确率低的排查思路技能选择准确率低是最常见的问题。排查思路我总结了一个三步法。第一步检查技能描述是否有重叠。如果两个技能的描述都包含查询、数据这样的词模型就容易混淆。解决办法是让每个技能的描述都有独特的意图关键词。比如查询库存和查询订单要明确区分开不要都写成查询数据。第二步检查示例是否足够典型。示例是模型做少样本学习的重要依据。如果示例太少或者太偏模型就学不到正确的匹配模式。我建议每个技能至少给3个示例覆盖不同的表达方式。第三步检查候选技能数量是否过多。如果粗筛返回了30个候选技能模型的选择难度就会大幅增加。解决办法是调整向量检索的top_k或者优化技能描述的向量质量。5.2 参数填充错误的常见原因参数填充错误通常有三个原因。第一个原因是参数名称不够直观。比如你把参数命名为pn模型根本不知道这是什么。参数名称要写全product_name就比pn好得多。第二个原因是参数描述不够清晰。比如warehouse参数只写仓库模型不知道是填仓库名称还是仓库编号。要写清楚仓库名称如华东仓、华南仓。第三个原因是缺少默认值。如果某个参数大部分情况下都不需要用户提供就应该给它设一个默认值而不是标成必填。必填参数越多模型出错的概率越大。5.3 技能执行超时的处理策略技能执行超时是另一个高频问题。处理策略分三层。第一层是预防。在技能实现里加超时控制比如用signal.alarm或者concurrent.futures的timeout参数。不要让技能无限期挂起。第二层是降级。超时之后返回一个降级结果而不是直接报错。比如查询库存超时了可以返回库存系统当前繁忙请稍后重试同时把这次查询加入重试队列。第三层是熔断。如果某个技能连续多次超时就暂时把它从技能池里摘掉避免模型反复选择它。等过一段时间再重新加入。5.4 常见问题速查表问题现象可能原因排查方法解决措施技能不被触发描述与用户意图不匹配检查description是否写了用户语言改写description加入用户常用表达选错技能技能描述重叠对比多个技能的description增加独特意图关键词减少重叠参数填错参数名称或描述不清晰检查参数schema重命名参数补充描述和示例执行超时底层服务响应慢查看技能执行日志加超时控制加降级逻辑重复执行模型重复调用查看调用日志加幂等键加去重判断结果格式错误返回结构不符合预期检查handler返回值统一返回格式加结果校验5.5 独家避坑技巧第一个技巧技能描述里不要出现或者这个词。比如查询库存或者订单模型会困惑到底该查哪个。一个技能只做一件事描述里只写这一件事。第二个技巧给技能加版本号。技能是会迭代的加了版本号之后出问题可以快速回滚。版本号建议用语义化版本比如query_inventory1.2.0。第三个技巧技能执行日志要记录完整的输入输出。这样出问题的时候可以复现。日志里要包含用户原始请求、模型选择的技能、填充的参数、执行结果、耗时。第四个技巧定期做技能回归测试。准备一批典型的用户请求定期跑一遍看看技能选择准确率和参数填充准确率有没有下降。我一般每周跑一次发现下降就及时调整。6. 技能编排的进阶玩法从单技能到技能链6.1 技能链的自动编排逻辑单技能能解决的问题有限真正复杂的任务需要技能链。技能链的自动编排逻辑是根据用户请求先识别出最终目标然后反向推导需要哪些技能最后按依赖关系排序。举个例子用户说帮我生成上个月的销售报告。最终目标是生成销售报告这个目标对应的技能是generate_report。generate_report的前置依赖是销售数据和图表对应的技能是query_sales_data和create_chart。create_chart的前置依赖是销售数据已经由query_sales_data提供了。所以最终的技能链是query_sales_data-create_chart-generate_report。这个反向推导的过程可以用一个简单的依赖图算法来实现。每个技能声明自己的requires和produces编排器根据这些声明构建依赖图然后做拓扑排序。6.2 技能链执行中的状态传递技能链执行时上游技能的输出要传递给下游技能。传递方式有两种一种是显式传递下游技能声明自己需要哪个上游技能的哪个输出字段另一种是隐式传递所有上游输出都放进一个共享的上下文对象下游技能自己从上下文里取。我推荐显式传递因为隐式传递容易造成字段名冲突和依赖混乱。显式传递的写法是在技能定义里加一个inputs字段声明每个输入来自哪个技能的哪个输出。skill_id: create_chart inputs: - name: sales_data from: query_sales_data.output.records - name: chart_type from: user_request.chart_type default: bar这种写法让依赖关系一目了然排查问题的时候也方便。6.3 技能链的容错与回滚技能链执行到一半失败了怎么办这是必须考虑的问题。我的做法是每个技能执行前先保存一个检查点记录当前上下文状态。如果某个技能失败就从最近的检查点恢复然后尝试替代方案。替代方案可以是换一个技能也可以是跳过这个技能用默认值继续。比如create_chart失败了可以跳过图表生成直接生成纯文本报告。这样至少能给用户一个部分可用的结果而不是完全失败。回滚的粒度也要考虑。如果技能链里有写入操作回滚就要把写入的数据撤销。这块建议用事务或者补偿操作来实现。补偿操作是指为每个写入技能配一个对应的撤销技能失败时调用撤销技能。6.4 技能链的性能优化技能链执行时间等于各个技能执行时间之和。如果链很长总时间就会很长。优化思路有三个。第一个是并行执行。如果两个技能之间没有依赖关系就可以并行执行。比如query_sales_data和query_inventory_data互不依赖可以同时跑。第二个是缓存。如果某个技能的输入参数相同就可以直接返回缓存结果不用重新执行。缓存的有效期根据业务特点来定查询类技能可以缓存5分钟写入类技能不缓存。第三个是预取。如果编排器能预测到下一步大概率会调用某个技能就可以提前开始执行。比如用户问完库存之后大概率会问价格就可以提前把价格数据查出来。7. 技能生态的扩展与维护让技能池持续生长7.1 技能贡献的标准化流程当团队里多个人都在往技能池里加技能时就需要一个标准化的贡献流程。我建议的流程是提案 - 评审 - 实现 - 测试 - 上线。提案阶段要写清楚这个技能解决什么问题、目标用户是谁、预期调用频率是多少。评审阶段要检查技能描述是否清晰、参数设计是否合理、是否与现有技能重叠。实现阶段要遵循统一的代码规范。测试阶段要覆盖正常路径和异常路径。上线之后要监控调用量和成功率。这个流程看起来重但能避免技能池变成垃圾场。我见过太多项目技能池里堆了几百个技能但真正被调用的不到二十个剩下的都是没人维护的僵尸技能。7.2 技能质量的评估指标技能质量怎么评估我关注四个指标调用成功率、平均执行耗时、参数填充准确率、用户满意度。调用成功率是指技能被调用后成功返回结果的比例。低于90%就要排查原因。平均执行耗时是指技能从开始执行到返回结果的平均时间。超过5秒就要考虑优化。参数填充准确率是指模型填充的参数正确的比例。低于85%就要优化参数schema。用户满意度可以通过用户反馈或者隐式信号比如用户是否重新提问来评估。7.3 技能的下线与归档技能不是只增不减的。当某个技能连续30天调用量为零或者调用成功率持续低于50%就应该考虑下线。下线之前先归档把技能定义、实现代码、历史调用日志打包保存以备将来需要时恢复。归档的技能要从技能注册表和向量数据库里移除避免占用检索资源。同时要在团队内部公告让大家都知道这个技能已经下线了。7.4 技能池的版本管理技能池本身也需要版本管理。每次技能增删改都应该打一个版本标签。这样出问题的时候可以快速回滚到上一个稳定版本。版本管理我建议用Git来做。技能定义文件和实现代码都放在Git仓库里每次变更走Pull Request流程。上线的时候打TagTag的命名规则是skills-v{主版本}.{次版本}.{补丁版本}。8. 我在实际项目中的几点体会做智能体技能化这件事我最大的体会是技能设计不是技术问题而是认知问题。你得先想清楚用户会怎么问、模型会怎么理解、执行层会怎么处理然后才能设计出好用的技能。很多团队一上来就写代码结果技能描述写得一塌糊涂模型根本选不对最后怪模型不行。其实问题出在技能设计上。另一个体会是技能池要小而精不要大而全。我见过一个项目技能池里有三百多个技能但实际高频调用的只有十几个。剩下的技能不仅没带来价值反而增加了模型的选择难度。我的建议是先把最高频的十个场景做成技能跑通了再逐步扩展。还有一个体会是技能的可观测性非常重要。每个技能的调用都要有日志日志里要包含完整的输入输出和耗时。这样出问题的时候才能快速定位。我一般会在技能执行器里统一加日志而不是让每个技能自己打日志这样格式统一排查起来方便。最后分享一个小技巧技能描述写完之后找几个不懂技术的人读一遍问他们你觉得这个技能是干什么的。如果他们能准确说出来说明描述写得好如果他们说不出来或者理解偏了说明描述还需要改。这个办法比任何自动化测试都管用因为最终用户就是不懂技术的人模型要理解的是他们的语言而不是技术文档的语言。 agent-skills：智能体技能封装与编排的工程化实践
1. 从agent-skills这个标题说起它到底在解决什么问题第一次看到agent-skills这个项目标题我的直觉是这大概率是一个围绕智能体能力封装、复用与编排的工程化项目。为什么这么判断因为agent这个词在过去两年里已经从学术论文里的抽象概念变成了工程落地中的具体模块而skills这个词则直接指向了能力——不是模型本身的能力而是模型之外、可以被调用、被组合、被版本管理的那一层能力。说白了大模型本身是个通才但通才不等于专家。你让它写首诗、编个故事它信手拈来但你让它去查一下某个内部系统的库存、按公司规范生成一份周报、或者调用某个特定API完成一次数据同步它就开始抓瞎了。原因很简单模型的知识截止于训练数据它的行动能力受限于它被赋予的工具。而agent-skills要做的就是把这层工具流程约束打包成一个个可插拔的技能模块让智能体在需要的时候按需加载、按需执行。这个项目适合谁来参考我梳理了三类人。第一类是正在做智能体应用开发的工程师你们可能已经踩过每个业务场景都从头写一遍工具调用逻辑的坑这个项目能帮你把重复劳动抽象掉。第二类是对智能体架构感兴趣的产品经理或技术负责人你们需要理解技能这个抽象层到底怎么设计、边界在哪里。第三类是刚入门AI应用开发的新手你们可以从这个项目里看到一个完整的、可运行的技能编排范式而不是停留在调个API就完事的层面。我个人的判断是agent-skills这类项目的核心价值不在于它实现了多少个技能而在于它定义了一套技能如何被描述、被发现、被调用、被组合的协议。这套协议才是真正能沉淀下来的东西。接下来我会从设计思路、核心细节、实操过程、问题排查四个维度把这个项目拆开揉碎讲清楚。2. 整体设计与思路拆解为什么是技能而不是工具2.1 从工具调用到技能封装的认知升级早期做智能体应用大家的做法很直接给模型一个工具列表每个工具就是一个函数模型根据用户意图选择调用哪个函数。这种做法在工具数量少的时候没问题一旦工具数量超过十个模型的选择准确率就会明显下降。我实测过一个场景当工具数量从5个增加到20个时模型选错工具的概率从不到5%飙升到接近30%。这不是模型不行而是扁平化的工具列表本身就不符合人类解决问题的认知模式。人类专家解决问题时脑子里不是装着一个几百项的工具清单而是装着若干个技能包。比如一个运维专家他的技能包里可能有排查服务异常、扩容集群、回滚版本这几个高阶技能每个技能内部又包含若干具体操作。当他面对一个问题时先匹配技能包再在技能包内部细化操作。这种分层匹配的策略才是agent-skills这类项目要复现的核心思路。所以这个项目的第一个设计决策就是把技能作为一等公民而不是把工具作为一等公民。技能是对工具的封装一个技能可以包含多个工具调用、多个条件分支、多个后处理步骤。这样做的好处是模型只需要在技能这一层做选择选择空间被大幅压缩准确率自然就上去了。2.2 技能描述协议的设计考量技能要被模型理解和调用就必须有一套描述协议。这套协议要回答几个问题这个技能是干什么的什么时候该用它用它需要提供什么参数它会返回什么执行过程中有哪些约束我见过不少项目在这块偷懒直接把函数的docstring扔给模型。这种做法能用但不够好。原因是docstring是写给程序员看的不是写给模型看的。模型需要的是意图匹配层面的描述而不是参数类型层面的描述。举个例子一个查询天气的工具docstring可能写的是get_weather(city: str) - dict但模型需要的是当用户询问某个城市的天气状况、温度、是否下雨时使用此技能需要提供城市名称。agent-skills在这块的设计思路是技能描述采用意图约束示例的三段式结构。意图说明这个技能解决什么问题约束说明使用时的前置条件和边界示例给出几个典型的调用场景。这种结构的好处是模型在做技能选择时可以同时参考语义匹配和示例匹配准确率比单纯依赖意图描述要高出一截。2.3 技能加载与执行的分离设计另一个值得说的设计决策是技能的加载和执行是分离的。加载阶段只负责把技能的元信息描述、参数schema、依赖关系注册到智能体的技能池里执行阶段才真正去调用底层工具。这种分离带来的好处是智能体可以在不执行任何实际操作的情况下先知道自己有哪些技能可用从而在规划阶段就做出更合理的决策。我打个比方这就像你去一家餐厅吃饭菜单是加载阶段你看着菜单决定点什么厨房做菜是执行阶段你点完之后厨师才开始干活。如果菜单和厨房混在一起你每看一道菜厨师就做一道那效率就太低了。分离设计让智能体可以先看全菜单再下单规划质量会明显提升。2.4 为什么选择这种架构而不是其他方案市面上做智能体能力扩展的方案不止一种。有的方案走的是微调路线把能力直接训进模型里有的方案走的是提示词工程路线靠复杂的prompt来引导模型还有的方案走的是工作流编排路线把整个流程固定死。agent-skills选择的是技能插件化路线我认为这个选择是合理的。微调路线成本高、迭代慢而且一旦模型更新之前微调的能力可能就失效了。提示词工程路线灵活但脆弱prompt稍微改几个字模型的行为就可能跑偏。工作流编排路线稳定但僵化无法应对开放式的用户请求。技能插件化路线在灵活性和稳定性之间取了一个平衡点技能本身是稳定的、可测试的但技能的选择和组合是动态的、由模型决定的。3. 核心细节解析与实操要点技能模块的解剖3.1 技能定义文件的结构一个技能的定义文件通常包含以下几个部分技能标识、技能描述、参数schema、执行逻辑、依赖声明、以及可选的示例。我用一个虚构的查询库存技能来举例说明。skill_id: query_inventory description: 当用户询问某个商品的库存数量、是否缺货、补货时间时使用此技能 parameters: - name: product_name type: string required: true description: 商品名称支持模糊匹配 - name: warehouse type: string required: false description: 指定仓库名称不填则查询所有仓库 constraints: - 商品名称不能为空 - 单次查询最多返回50条记录 examples: - input: 查一下A商品的库存 output: A商品在华东仓有120件华南仓有80件 - input: B商品缺货吗 output: B商品当前总库存为0预计3天后补货这个结构里description是给模型做意图匹配用的parameters是给模型做参数填充用的constraints是给执行层做校验用的examples是给模型做少样本学习用的。四者缺一不可。注意description的写法非常关键。我踩过的坑是早期把description写得太技术化比如调用库存数据库查询接口结果模型经常在用户问这个商品还有货吗的时候不触发这个技能。后来改成当用户询问商品库存、缺货、补货相关问题时使用触发率立刻上来了。description要写用户意图不要写技术实现。3.2 参数schema的设计陷阱参数schema看起来简单实际上坑很多。最常见的坑是参数类型过于严格。比如你把warehouse参数定义成枚举类型只允许华东仓、华南仓、华北仓三个值。但用户可能说上海仓、广州仓模型在填充参数时就会失败。我的经验是对于面向用户的参数尽量用string类型加模糊匹配把严格的校验放到执行层去做。执行层拿到上海仓之后可以通过别名映射表把它转换成华东仓。这样模型不用背仓库别名执行层也不用担心模型填错。另一个坑是必填参数过多。如果一个技能需要用户提供五个必填参数模型大概率会漏填或者瞎填。我的做法是必填参数不超过两个其余的都设成可选执行层根据可选参数的缺失情况做降级处理。比如查询库存时product_name必填warehouse可选不填就查全部。3.3 技能执行逻辑的编写要点执行逻辑是技能真正干活的地方。这块的编写要点有三个幂等性、超时控制、错误封装。幂等性是指同一个技能用同样的参数调用多次结果应该是一致的。这对于查询类技能天然满足但对于写入类技能就需要特别注意。比如一个创建工单的技能如果模型因为某种原因重复调用了两次就会创建两个重复工单。解决办法是在执行逻辑里加去重判断或者引入幂等键。超时控制是指技能执行不能无限期挂起。我建议每个技能都设置一个超时时间查询类技能5秒写入类技能15秒复杂计算类技能30秒。超时之后返回一个明确的错误信息让模型知道这个技能暂时不可用而不是一直等下去。错误封装是指技能执行失败时返回给模型的错误信息要模型友好。不要把原始的堆栈信息扔给模型那样模型看不懂。要把错误转换成自然语言描述比如库存系统当前不可用请稍后重试或者未找到名为XXX的商品请确认商品名称是否正确。3.4 技能之间的依赖与组合单个技能能解决的问题有限真正有价值的是技能的组合。比如生成月度销售报告这个任务可能需要依次调用查询销售数据、计算同比环比、生成图表、导出PDF四个技能。agent-skills处理技能组合的方式是允许技能声明自己的前置依赖和后置产出。前置依赖说明这个技能需要哪些数据作为输入后置产出说明这个技能会生成哪些数据。智能体在规划时可以根据依赖关系自动编排技能的执行顺序。这块的实操要点是依赖声明要尽量细粒度。不要说需要销售数据而要说需要指定月份的销售明细列表。细粒度的依赖声明让智能体更容易找到匹配的上游技能。4. 实操过程与核心环节实现从零搭建一个技能4.1 环境准备与项目初始化假设我们要从零搭建一个基于agent-skills范式的智能体应用第一步是环境准备。我推荐的技术栈是Python 3.10以上版本配合一个轻量的Web框架比如FastAPI来暴露技能接口用一个向量数据库比如Chroma或FAISS来做技能描述的语义检索。为什么需要向量数据库因为当技能数量超过50个时把所有技能描述塞进prompt里会超出上下文窗口。用向量数据库做一次粗筛只把最相关的10个技能描述塞进prompt既节省token又提升准确率。项目初始化的目录结构我建议这样组织agent-skills-demo/ skills/ __init__.py query_inventory.py create_ticket.py generate_report.py registry/ skill_registry.py vector_store.py executor/ skill_executor.py error_handler.py config/ settings.yaml main.pyskills目录放各个技能的实现registry目录放技能注册和检索逻辑executor目录放技能执行和错误处理逻辑config放配置文件。4.2 技能注册流程的实现技能注册的核心逻辑是扫描skills目录下的所有技能定义解析元信息写入技能注册表同时把技能描述向量化后存入向量数据库。import importlib import os from registry.vector_store import VectorStore class SkillRegistry: def __init__(self, skills_dir, vector_store): self.skills_dir skills_dir self.vector_store vector_store self.skills {} def register_all(self): for filename in os.listdir(self.skills_dir): if filename.endswith(.py) and not filename.startswith(__): module_name filename[:-3] module importlib.import_module(fskills.{module_name}) skill_def module.SKILL_DEFINITION self.skills[skill_def[skill_id]] skill_def self.vector_store.add( skill_def[skill_id], skill_def[description] ) print(f已注册 {len(self.skills)} 个技能)这段代码的关键点是技能定义以模块级变量SKILL_DEFINITION的形式暴露注册器通过动态导入的方式加载。这样做的好处是新增技能只需要在skills目录下加一个文件不需要修改注册器的代码。4.3 技能检索与选择的实现技能检索分两步先用向量检索做粗筛再用模型做精排。def select_skills(self, user_query, top_k10): candidates self.vector_store.search(user_query, top_ktop_k) candidate_descriptions [] for skill_id in candidates: skill self.skills[skill_id] candidate_descriptions.append( f技能ID: {skill_id}\n描述: {skill[description]}\n f参数: {skill[parameters]}\n示例: {skill.get(examples, [])} ) prompt f用户请求{user_query}\n\n可选技能\n \n---\n.join(candidate_descriptions) prompt \n\n请选择最合适的技能并给出调用参数。如果不需要任何技能返回NONE。 response call_llm(prompt) return parse_skill_selection(response)这里的top_k我建议设成10到15之间。设太小可能漏掉相关技能设太大又浪费token。实测下来10是一个比较平衡的值。4.4 技能执行的完整链路技能执行的完整链路是解析模型返回的技能选择结果 - 校验参数 - 执行技能 - 封装结果 - 返回给模型。def execute_skill(self, skill_id, params): if skill_id not in self.skills: return {error: f技能 {skill_id} 不存在} skill self.skills[skill_id] validation_error self.validate_params(skill, params) if validation_error: return {error: validation_error} try: result skill[handler](**params) return {result: result} except TimeoutError: return {error: 技能执行超时请稍后重试} except Exception as e: return {error: f技能执行失败{str(e)}}参数校验这块我建议做两层第一层是类型校验检查参数类型是否匹配第二层是业务校验检查参数值是否在合理范围内。类型校验可以用pydantic自动完成业务校验需要手写。4.5 一个完整案例库存查询技能的实现我把库存查询技能的完整实现写出来方便你直接参考。SKILL_DEFINITION { skill_id: query_inventory, description: 当用户询问某个商品的库存数量、是否缺货、补货时间时使用此技能, parameters: [ {name: product_name, type: string, required: True, description: 商品名称支持模糊匹配}, {name: warehouse, type: string, required: False, description: 指定仓库名称不填则查询所有仓库} ], constraints: [ 商品名称不能为空, 单次查询最多返回50条记录 ], examples: [ {input: 查一下A商品的库存, output: A商品在华东仓有120件}, {input: B商品缺货吗, output: B商品当前总库存为0} ], handler: None } def query_inventory_handler(product_name, warehouseNone): if not product_name: raise ValueError(商品名称不能为空) results db.query_inventory(product_name, warehouse) if len(results) 50: results results[:50] if not results: return f未找到名为{product_name}的商品 summary [] for r in results: summary.append(f{r[warehouse]}有{r[quantity]}件) return f{product_name}的库存情况 .join(summary) SKILL_DEFINITION[handler] query_inventory_handler这个实现里handler函数是真正干活的SKILL_DEFINITION是给注册器用的。两者放在同一个文件里维护起来比较方便。5. 常见问题与排查技巧实录踩过的坑和填过的土5.1 技能选择准确率低的排查思路技能选择准确率低是最常见的问题。排查思路我总结了一个三步法。第一步检查技能描述是否有重叠。如果两个技能的描述都包含查询、数据这样的词模型就容易混淆。解决办法是让每个技能的描述都有独特的意图关键词。比如查询库存和查询订单要明确区分开不要都写成查询数据。第二步检查示例是否足够典型。示例是模型做少样本学习的重要依据。如果示例太少或者太偏模型就学不到正确的匹配模式。我建议每个技能至少给3个示例覆盖不同的表达方式。第三步检查候选技能数量是否过多。如果粗筛返回了30个候选技能模型的选择难度就会大幅增加。解决办法是调整向量检索的top_k或者优化技能描述的向量质量。5.2 参数填充错误的常见原因参数填充错误通常有三个原因。第一个原因是参数名称不够直观。比如你把参数命名为pn模型根本不知道这是什么。参数名称要写全product_name就比pn好得多。第二个原因是参数描述不够清晰。比如warehouse参数只写仓库模型不知道是填仓库名称还是仓库编号。要写清楚仓库名称如华东仓、华南仓。第三个原因是缺少默认值。如果某个参数大部分情况下都不需要用户提供就应该给它设一个默认值而不是标成必填。必填参数越多模型出错的概率越大。5.3 技能执行超时的处理策略技能执行超时是另一个高频问题。处理策略分三层。第一层是预防。在技能实现里加超时控制比如用signal.alarm或者concurrent.futures的timeout参数。不要让技能无限期挂起。第二层是降级。超时之后返回一个降级结果而不是直接报错。比如查询库存超时了可以返回库存系统当前繁忙请稍后重试同时把这次查询加入重试队列。第三层是熔断。如果某个技能连续多次超时就暂时把它从技能池里摘掉避免模型反复选择它。等过一段时间再重新加入。5.4 常见问题速查表问题现象可能原因排查方法解决措施技能不被触发描述与用户意图不匹配检查description是否写了用户语言改写description加入用户常用表达选错技能技能描述重叠对比多个技能的description增加独特意图关键词减少重叠参数填错参数名称或描述不清晰检查参数schema重命名参数补充描述和示例执行超时底层服务响应慢查看技能执行日志加超时控制加降级逻辑重复执行模型重复调用查看调用日志加幂等键加去重判断结果格式错误返回结构不符合预期检查handler返回值统一返回格式加结果校验5.5 独家避坑技巧第一个技巧技能描述里不要出现或者这个词。比如查询库存或者订单模型会困惑到底该查哪个。一个技能只做一件事描述里只写这一件事。第二个技巧给技能加版本号。技能是会迭代的加了版本号之后出问题可以快速回滚。版本号建议用语义化版本比如query_inventory1.2.0。第三个技巧技能执行日志要记录完整的输入输出。这样出问题的时候可以复现。日志里要包含用户原始请求、模型选择的技能、填充的参数、执行结果、耗时。第四个技巧定期做技能回归测试。准备一批典型的用户请求定期跑一遍看看技能选择准确率和参数填充准确率有没有下降。我一般每周跑一次发现下降就及时调整。6. 技能编排的进阶玩法从单技能到技能链6.1 技能链的自动编排逻辑单技能能解决的问题有限真正复杂的任务需要技能链。技能链的自动编排逻辑是根据用户请求先识别出最终目标然后反向推导需要哪些技能最后按依赖关系排序。举个例子用户说帮我生成上个月的销售报告。最终目标是生成销售报告这个目标对应的技能是generate_report。generate_report的前置依赖是销售数据和图表对应的技能是query_sales_data和create_chart。create_chart的前置依赖是销售数据已经由query_sales_data提供了。所以最终的技能链是query_sales_data-create_chart-generate_report。这个反向推导的过程可以用一个简单的依赖图算法来实现。每个技能声明自己的requires和produces编排器根据这些声明构建依赖图然后做拓扑排序。6.2 技能链执行中的状态传递技能链执行时上游技能的输出要传递给下游技能。传递方式有两种一种是显式传递下游技能声明自己需要哪个上游技能的哪个输出字段另一种是隐式传递所有上游输出都放进一个共享的上下文对象下游技能自己从上下文里取。我推荐显式传递因为隐式传递容易造成字段名冲突和依赖混乱。显式传递的写法是在技能定义里加一个inputs字段声明每个输入来自哪个技能的哪个输出。skill_id: create_chart inputs: - name: sales_data from: query_sales_data.output.records - name: chart_type from: user_request.chart_type default: bar这种写法让依赖关系一目了然排查问题的时候也方便。6.3 技能链的容错与回滚技能链执行到一半失败了怎么办这是必须考虑的问题。我的做法是每个技能执行前先保存一个检查点记录当前上下文状态。如果某个技能失败就从最近的检查点恢复然后尝试替代方案。替代方案可以是换一个技能也可以是跳过这个技能用默认值继续。比如create_chart失败了可以跳过图表生成直接生成纯文本报告。这样至少能给用户一个部分可用的结果而不是完全失败。回滚的粒度也要考虑。如果技能链里有写入操作回滚就要把写入的数据撤销。这块建议用事务或者补偿操作来实现。补偿操作是指为每个写入技能配一个对应的撤销技能失败时调用撤销技能。6.4 技能链的性能优化技能链执行时间等于各个技能执行时间之和。如果链很长总时间就会很长。优化思路有三个。第一个是并行执行。如果两个技能之间没有依赖关系就可以并行执行。比如query_sales_data和query_inventory_data互不依赖可以同时跑。第二个是缓存。如果某个技能的输入参数相同就可以直接返回缓存结果不用重新执行。缓存的有效期根据业务特点来定查询类技能可以缓存5分钟写入类技能不缓存。第三个是预取。如果编排器能预测到下一步大概率会调用某个技能就可以提前开始执行。比如用户问完库存之后大概率会问价格就可以提前把价格数据查出来。7. 技能生态的扩展与维护让技能池持续生长7.1 技能贡献的标准化流程当团队里多个人都在往技能池里加技能时就需要一个标准化的贡献流程。我建议的流程是提案 - 评审 - 实现 - 测试 - 上线。提案阶段要写清楚这个技能解决什么问题、目标用户是谁、预期调用频率是多少。评审阶段要检查技能描述是否清晰、参数设计是否合理、是否与现有技能重叠。实现阶段要遵循统一的代码规范。测试阶段要覆盖正常路径和异常路径。上线之后要监控调用量和成功率。这个流程看起来重但能避免技能池变成垃圾场。我见过太多项目技能池里堆了几百个技能但真正被调用的不到二十个剩下的都是没人维护的僵尸技能。7.2 技能质量的评估指标技能质量怎么评估我关注四个指标调用成功率、平均执行耗时、参数填充准确率、用户满意度。调用成功率是指技能被调用后成功返回结果的比例。低于90%就要排查原因。平均执行耗时是指技能从开始执行到返回结果的平均时间。超过5秒就要考虑优化。参数填充准确率是指模型填充的参数正确的比例。低于85%就要优化参数schema。用户满意度可以通过用户反馈或者隐式信号比如用户是否重新提问来评估。7.3 技能的下线与归档技能不是只增不减的。当某个技能连续30天调用量为零或者调用成功率持续低于50%就应该考虑下线。下线之前先归档把技能定义、实现代码、历史调用日志打包保存以备将来需要时恢复。归档的技能要从技能注册表和向量数据库里移除避免占用检索资源。同时要在团队内部公告让大家都知道这个技能已经下线了。7.4 技能池的版本管理技能池本身也需要版本管理。每次技能增删改都应该打一个版本标签。这样出问题的时候可以快速回滚到上一个稳定版本。版本管理我建议用Git来做。技能定义文件和实现代码都放在Git仓库里每次变更走Pull Request流程。上线的时候打TagTag的命名规则是skills-v{主版本}.{次版本}.{补丁版本}。8. 我在实际项目中的几点体会做智能体技能化这件事我最大的体会是技能设计不是技术问题而是认知问题。你得先想清楚用户会怎么问、模型会怎么理解、执行层会怎么处理然后才能设计出好用的技能。很多团队一上来就写代码结果技能描述写得一塌糊涂模型根本选不对最后怪模型不行。其实问题出在技能设计上。另一个体会是技能池要小而精不要大而全。我见过一个项目技能池里有三百多个技能但实际高频调用的只有十几个。剩下的技能不仅没带来价值反而增加了模型的选择难度。我的建议是先把最高频的十个场景做成技能跑通了再逐步扩展。还有一个体会是技能的可观测性非常重要。每个技能的调用都要有日志日志里要包含完整的输入输出和耗时。这样出问题的时候才能快速定位。我一般会在技能执行器里统一加日志而不是让每个技能自己打日志这样格式统一排查起来方便。最后分享一个小技巧技能描述写完之后找几个不懂技术的人读一遍问他们你觉得这个技能是干什么的。如果他们能准确说出来说明描述写得好如果他们说不出来或者理解偏了说明描述还需要改。这个办法比任何自动化测试都管用因为最终用户就是不懂技术的人模型要理解的是他们的语言而不是技术文档的语言。