做了好一阵子大模型Agent相关的项目我发现一个特别有意思的现象很多人一开始追求把工具tool做得又多又全结果模型在真实任务里频繁选错工具、拼错参数、中途翻车。真正让Agent“好用”的往往不是你给它多少把螺丝刀而是你教会它“怎么修好一台机器”——这正是我最近在整理的这套 agent-skills 技能库方案想解决的事。简单说agent-skills 不是又一份工具清单而是一套把“单点能力”升级成“可复用技能”的封装框架。它给每个技能配上元数据、参数约束、执行钩子、失败恢复逻辑让 Agent 在接到任务时像老师傅一样“凭经验干活”而不是每次从零推理。这套思路适合正在做 Agent 应用、RAG 工作流、自动化助手的朋友参考也适合想弄明白“技能与工具到底差在哪”的开发者。我会把设计思路、落地代码、踩坑实录都摊开讲尽量让不同基础的读者都能拿去用。1. 内容整体设计与思路拆解1.1 为什么 Agent 需要“技能库”而不是一堆函数先聊一个常见场景。假设你想让 Agent 帮你“整理一篇会议纪要”你可能会给它挂上三个工具一个做语音转写、一个调大模型做摘要、一个发邮件。模型确实能按顺序调这三个工具但每次执行都要重新理解任务、重新组织参数、重新处理中间结果。任务一多、上下文一变它就很容易在第二步忘了第三步的前提或者在参数上犯低级错误。问题不在于模型笨而在于我们只用 function calling 暴露了“零件”却没有给它“工序”。工具调用解决的是“单点动作”技能要解决的是“会做一件事”。在 agent-skills 里一个技能内部可以包含多个工具调用、多步状态流转、前置条件检查和输出校验。它像一个封装好的黑盒模型只需要知道“这个技能能搞定会议纪要”至于内部怎么转写、怎么摘要、怎么格式化都不需要重新决策。我常用一个比喻工具是一抽屉零件技能是一套成熟工序。给 Agent 一百个零件它未必能组装出一台机器给它十道工序它反而能稳定交付结果。技能库的价值就是把“零件”按场景组织成“工序”并且让模型在接到任务时能快速检索到最合适的工序。1.2 “技能”与“工具调用”的边界在哪里我踩过不少坑之后总结出技能和工具的几个核心区别看下面这张表比较直观对比维度工具Tool技能Skill粒度单点能力如“发HTTP请求”多步骤任务如“抓取网页并提炼要点”状态无状态每次调用独立有内部状态支持阶段流转复用性可被不同技能引用本身是复用的最小业务单元容错通常由调用方处理错误自带前置检查、后置校验、降级恢复描述侧重说明“我能做什么动作”说明“我适合解决什么任务”工具是技能的“底座”技能是工具的“编排层”。举个例子一个搜索技能内部会调用检索 API工具但它还会做三件工具本身不做的事第一把用户的模糊问题拆成 2-3 个具体检索词第二对检索结果做相关度过滤第三如果主搜索源超时自动切到备选搜索源。这些动作叠加起来才是“会搜索”这个技能。从工程角度看把技能和工具分开还有一个现实好处工具的接口往往随外部服务变动而技能的对外契约名称、描述、入参出参可以保持稳定。这样 Agent 层面的提示词和路由逻辑就不用频繁改底层换了供应商也不影响上层行为。1.3 技能库的整体架构分层我在设计 agent-skills 时把整个框架拆成了四层注册中心、执行引擎、上下文管理器、评估器。分层的核心原因只有一个——把“检索”和“执行”解耦把“状态”和“逻辑”分离这样后续加技能、调技能都不会牵一发动全身。注册中心负责维护所有技能的元数据包括名称、描述、标签、参数 Schema、优先级。Agent 接到任务后第一步不是直接执行而是先来注册中心“找技能”。这一步可以做成关键词粗筛也可以叠加向量检索把候选技能从几百个缩小到三到五个。执行引擎拿到候选技能后负责加载技能实例、执行前置钩子、运行主逻辑、触发后置校验并且在失败时调用恢复策略。上下文管理器比较容易被忽略它的职责是把技能执行过程中的关键中间状态暂存起来比如“当前进行到第几步”“上一步产出了什么”这样组合技能才能有序推进。评估器则是一个闭环反馈模块它记录每次技能调用的命中率、成功率、token 消耗方便你持续优化技能描述和执行逻辑。这四层配合起来整体流程大概是这样Agent 收到用户任务向注册中心发起检索拿到最匹配的技能描述后把任务参数交给执行引擎引擎按技能内部定义好的阶段逐步执行每走一步都从上下文管理器读写状态最终结果通过评估器记录质量再把关键信息写回技能的记忆缓存作为下次执行的参考。后面我会给一个简化版实现方便你理解每个环节到底做了什么。2. 核心细节解析与实操要点2.1 技能描述Agent 选择技能的“门面”如果你只能优化一件事我会毫不犹豫地建议你打磨技能描述。因为技能实现得再完美模型找不到它、或者把它和别的技能搞混等于白写。技能描述本质上是写给大模型看的“使用说明书”它的目标不是让人类看懂而是让模型在“什么场景下该选中我”这件事上没有歧义。我写技能描述时会遵照一个检查清单意图关键词、适用场景、输入限制、输出格式、使用禁忌。意图关键词帮助模型快速匹配比如“会议纪要”技能的描述里要有“总结、纪要、提炼、议题”这些词适用场景要写清楚“什么任务适合你”比如“当用户提供会议录音或速记文稿需要输出结构化纪要时”输入限制要写明白“你能接收什么格式”比如“支持 txt、md不支持音视频直接输入”输出格式则要说明“你返回什么东西”比如“返回包含议题列表、结论、待办事项的 Markdown 文本”使用禁忌同样重要用来排除边界情况比如“用户只要求翻译时不要使用本技能”。这里放一个正反对比你感受一下差别。反例描述“对文本进行摘要。”——太宽泛模型不知道什么时候该用。正例描述“当用户提供一篇文章、报告或网页正文需要提炼核心观点和关键数字时使用。输入为纯文本输出为 200 字以内的要点列表。若用户仅要求翻译或改写不使用本技能。”你看后者直接帮模型把决策边界框好了。还有一个实操细节描述不要写实现细节。我见过有人把内部调用了几个 API、用了什么模型都写进技能描述里这纯属浪费 token模型根本不关心这些。描述里只需要写“任务特征”和“契约约束”实现细节放到技能内部文档里就好。2.2 技能实现从需求到代码的落地规范技能描述解决的是“模型怎么找到我”技能实现解决的是“找到之后怎么稳定跑完”。我在 agent-skills 里给每个技能定义了一套标准钩子相当于给技能执行流程立了个规矩环境准备在前、核心逻辑居中、结果校验在后、出错有兜底。以 Python 为例一个技能类大致长这样from pydantic import BaseModel class SkillInput(BaseModel): text: str max_points: int 200 class SummarySkill: name summary_skill description 当用户提供文章或报告需要提炼核心观点时使用... def before_run(self, payload: SkillInput): # 前置检查确认输入非空、长度合规 if not payload.text.strip(): raise ValueError(text cannot be empty) return payload def run(self, payload: SkillInput): # 核心逻辑调用摘要模型整理要点 points self._call_summarizer(payload.text, payload.max_points) return points def after_run(self, output): # 后置校验确保输出非空且是列表 if not isinstance(output, list) or len(output) 0: raise RuntimeError(summary output is invalid) return output def on_error(self, exc: Exception): # 兜底逻辑记录错误并返回可读信息 return {error: str(exc), fallback: None}这套钩子的价值在于它把每个技能的“生命周期”固定下来执行引擎只管按顺序调用钩子技能自己管内部的业务细节。以后无论是加日志、加监控还是做重试都落在框架层面而不需要改每个技能。另一个我特别想强调的规范是参数校验。不要指望大模型每次都给你传出完美的参数它经常会把字符串传成数字、把必填字段漏掉。所以每个技能的入参一律用 Pydantic 这类 Schema 约束在 before_run 阶段就校验掉绝不要等到 run 内部再花力气解析脏参数。参数校验的本质是把“信任模型”改成“验证模型”这是一种成本极低的防御手段。最后提一个原则技能尽量做到“幂等或可恢复”。所谓幂等就是同一个输入跑两次结果一致所谓可恢复就是跑到一半挂了下次可以接着跑而不是从头再来。幂等能省掉很多重复执行的麻烦可恢复则能避免外部副作用比如发了一封重复邮件带来的事故。做不到幂等的时候至少要保证 on_error 里能明确告诉调用方“我已经做到哪一步了”。2.3 技能注册与检索让 Agent 快速找到技能有了技能类下一步就是把它们登记到注册中心并且让 Agent 在一个能接受的时延内找到该用的那个。这里有个关键约束随着技能增多你不能把所有技能描述一股脑塞进系统 Prompt否则上下文很快爆炸而且模型面对几十个相似描述时会眼花缭乱。可行的方案是“粗筛 精排”两步走。粗筛阶段注册中心根据用户任务的文本按技能名称、标签、描述里的关键词做一轮快速过滤把几百个技能缩小到 TopK我一般取 5 个。这一步速度极快不需要调用模型。精排阶段把粗筛出的技能描述拼接成一段短列表交给模型做最终选择让它判断哪个技能最匹配当前任务。精排只关乎几十个候选token 消耗可控选择准确率却比“直接塞所有技能”高不少。如果技能数量特别大比如超过一千个我会再叠加一个 embedding 向量检索层。你可以给每个技能描述生成向量存进向量数据库用户请求进来后用同一个 embedding 模型编码请求文本做相似度检索把最接近的几十个技能送入粗排。这种做法在技能数量大时能有效提升召回率而且实现不难。需要注意的坑是技能描述里尽量不要出现和技能用途无关的“热门词”否则向量检索会把无关技能拉进来干扰后续精排。注册中心本身建议做成轻量服务独立于 Agent 主进程。这样技能更新不需要重启主要服务注册中心也可以单独做缓存和监控。我最初图省事把技能注册表写死在代码里结果每次加技能都要重新部署后来改成独立服务之后加技能的热更新终于顺畅了。3. 实操过程与核心环节实现3.1 第一个技能一个关键词搜索技能理论说了不少现在落地走一遍。我从最简单的技能开始讲关键词搜索。这个技能的目标不是“给你一个搜索链接”而是“根据问题自动生成检索词调用搜索接口并把返回结果整理成干净列表”。拆解来看它包含四个步骤生成检索词、调用搜索 API、过滤无效结果、返回结构化数据。下面是一段简化后的实现骨架class SearchSkill: name search_skill description ( 当用户需要查找最新资料、新闻、文档或网络信息时使用。 输入为自然语言问题我会自动生成2-3个具体检索词并执行搜索 返回按相关度排序的结果列表。 ) def before_run(self, payload: SkillInput): if not payload.query.strip(): raise ValueError(query is empty) return payload def run(self, payload: SkillInput): # 1. 用轻量模型将用户问题拆成多个具体检索词 keywords self._expand_queries(payload.query) # 2. 依次调用搜索API合并返回结果 raw_results [] for kw in keywords: raw_results.extend(self._call_search_api(kw, top5)) # 3. 过滤掉重复和明显无关的条目 return self._dedup_and_filter(raw_results) def after_run(self, output): if not output: return {has_results: False, items: []} return {has_results: True, items: output[:10]}我第一次测试这个技能时发现模型最常犯的错误是“检索词写得太宽泛”。比如用户问“Agent 框架有哪些新进展”模型直接生成一个“Agent 框架进展”这种大而无当的检索词搜出来的结果大多不是近期的有效信息。后来我在技能描述里加了一句明确指示“将检索词拆成 2-3 个具体的短语组合比如‘Agent 框架 2025 开源项目’、‘LangChain 新功能 发布’。”加了这一句之后搜索结果的质量提升非常明显。这再次印证了我在 2.1 里说的技能描述里写清“怎么做事”往往比单纯堆逻辑更能改变模型行为。测试完整链路时我会模拟一条用户消息观察 Agent 是否选中 SearchSkill以及传给技能的 query 参数是否合理。如果模型没选中多半是描述里的意图关键词还不够直观如果选中了但参数不对多半是参数 Schema 写得不够清楚。这两类问题在前期会反复出现属于正常磨合过程。3.2 组合技能把多个原子技能编排成复杂流程单点技能只能解决一步操作真实任务往往需要多步配合这时候就要写“组合技能”。组合技能的核心设计是内部维护一个阶段状态机把多个原子技能按顺序串联起来并在每个阶段落盘中间产物。拿“整理技术周报”来举例。这个任务实际上要完成三件事搜索本周的技术热点、对每篇热点生成摘要、把所有摘要汇总成固定格式的周报。在 agent-skills 里我写了一个 ReportSkill内部注册了 SearchSkill、SummarySkill、FormatSkill 三个子技能并定义了三个阶段class ReportSkill: stages [search, summarize, format] def run(self, payload): state self.state_manager.new_session() # stage 1: 搜索热点 if state.stage search: hits self.call_sub_skill(search_skill, payload.topic) state.update({hits: hits, stage: summarize}) self.state_manager.save(state) # stage 2: 逐篇摘要 if state.stage summarize: summaries [ self.call_sub_skill(summary_skill, h[content]) for h in state.hits[:5] ] state.update({summaries: summaries, stage: format}) self.state_manager.save(state) # stage 3: 汇总输出 if state.stage format: return self.call_sub_skill(format_skill, state.summaries)几个关键点需要特别说明。第一阶段状态必须保存在技能实例之外最好放到独立的 state_manager 里否则并发请求会串状态。我最初把所有状态都挂在技能对象上两个请求同时进来直接互相污染排查了半天才发现是这个原因。第二组合技能在描述里必须写清楚“我会依次做什么”比如描述里写“我会先搜索本周科技资讯再对前五篇生成摘要最后汇总为周报格式”这样模型调用后不会对中间结果的形态产生错误预期。第三组合技能内部调用子技能时仍要复用子技能本身的参数校验和错误处理不要在组合层面重新解析一遍结果——这既浪费 token又容易把错误掩盖掉。组合技能是 agent-skills 里最实用的部分。它能让你把“多步骤任务”沉淀成可复用的经验而不是让模型每次临时规划步骤。从工程效率看这相当于把 Agent 的“临场发挥”逐步变成“熟能生巧”。3.3 技能评估怎么判断技能好不好用技能库越扩越大你会面临一个更现实的问题怎么判断技能到底好不好用我在早期一直凭感觉调参结果经常是调完描述后感觉“应该变好了”却拿不出数据证明。后来我补了一套简单的评估流程分成离线和在线两部分。离线评估用历史任务做回归测试。我会收集过去一段时间内真实用户给 Agent 的任务请求把它们作为固定测试集。每次改完一个技能就把这批请求重跑一遍统计三个核心指标技能命中率模型是否选对了技能、参数正确率传给技能的参数是否合法、任务完成率技能是否产出合格结果。只要改动不导致这三个指标回退我才敢放心上线。在线评估则关注技能调用链路上的效率。我会在日志里记录每个技能实例的调用次数、平均耗时、平均 token 消耗、失败次数、恢复次数。这里我特别关注一个容易被忽略的指标单次技能调用消耗的平均 token。有些技能描述写得过长模型每次选择它都要阅读大量无关文本久而久之 token 成本很高。优化这些描述往往比换更贵的模型还划算。我整理过一张参考速查表供你评估自己技能库的健康度指标健康范围低于阈值说明技能命中率 85%描述意图不够清晰或检索排序有问题参数正确率 90%参数 Schema 和提示词需要补强任务完成率 80%技能内部逻辑或容错策略需要迭代平均恢复率 60%on_error 兜底太弱错误容易直接暴露给用户平均 token/调用越低越好描述冗余或内部逻辑重复读取无用信息这套评估体系不一定面面俱到但它至少能让我在“优化技能”这件事上不再靠感觉。每次改动技能我都能从数据里看到是命中率提升了还是 token 下降了这比“看起来不错”要踏实得多。4. 常见问题与排查技巧实录4.1 技能冲突与优先级之争技能多了之后第一个遇到的问题就是“两个技能看起来都能解决同一个任务”。比如我既有“周报生成技能”又有“日报汇总技能”用户说“帮我整理一下这周的工作”模型可能两个都匹配最后选错。这类问题的本质是技能描述在意图空间上发生了重叠。我的处理办法有两招。第一招在描述里主动加入“冲突排除条款”明确声明自己的边界。比如“日报汇总技能”描述里写“仅当用户明确提到‘日报’或‘今日工作’时使用如果提到‘周报’‘本周’请改用周报生成技能”。这看起来像是在给别的技能做广告但实践证明它恰恰能降低模型的决策困惑。第二招在注册中心给技能加一个优先级字段当粗筛得分相近时按优先级排序。注意优先级不能写死要基于实际命中率动态调整某个技能在同类任务里命中率更高它的优先级就自动上升。4.2 上下文爆炸与技能描述过长另一个高频问题是技能一多系统提示词越来越长。有些技能描述恨不得把用法、示例、注意事项全写进去结果模型在路由时反而抓不住重点而且每次请求都在空耗 token。这里我给自己定了一个硬性规则技能描述控制在 80 到 150 字详细说明放到技能类内部的一个usage字段里只在执行时才加载。执行引擎可以在 before_run 阶段读取 usage 字段作为技能内部的运行参考但不需要参与路由决策。我还踩过一个具体的坑把完整的技能源码和调用示例直接贴在描述里。看起来信息很全但模型实际上根本不会逐字阅读真正起作用的只有前一两句“应用场景描述”。后面那些代码块反而干扰了语义匹配让模型对技能的能力边界产生错误预期。删掉冗余内容之后命中率不但没降反而上涨了约 7 个百分点。4.3 容错与恢复技能翻车之后怎么办技能跑得再稳总会有翻车的时候。参数校验失败、外部服务超时、模型返回格式不对、下游接口报错这些在真实环境里避无可避。我的经验是不要追求“永不失败”而是追求“失败后可理解、可恢复”。on_error 钩子里至少要记录错误类型和当前阶段让上层 Agent 知道发生了什么以及能不能换一条路径继续。我总结了一张问题速查表按高频优先级列在下面错误类型常见原因解决建议参数 Schema 校验失败模型漏传字段或类型错误强化描述中的“需要输入什么”并加 before_run 校验外部服务超时第三方 API 响应过慢在 run 里加重试机制超时阈值设 2-3 次输出格式不合预期模型返回 Markdown 却需要 JSON在 after_run 里做强校验失败时触发重新生成阶段状态丢失并发会话污染或状态未落盘状态统一走 state_manager禁止挂在技能实例上子技能执行失败底层技能抛错未捕获组合技能要把子技能异常捕获并标记阶段进度针对超时和瞬态错误我的具体做法是在 run 阶段包一层重试装饰器第一次超时后重试一次并切换备选服务比如主搜索源失败就换备用源。如果第二次仍然失败直接走 on_error把“已经尝试两次”的信息返回给上层模型让它决定是否换一个技能或者询问用户。这一套下来技能库的稳定性提升明显用户面对“失败”时至少不会看到一团乱麻。还有一个容易忽略的点恢复策略要区分“可安全重试”和“不可安全重试”。比如发送邮件这种有副作用的操作重试前必须确认上一步是否真的失败了否则可能发两封邮件。我在可写操作的技能里都会加一个execution_id每次执行生成唯一 ID下游接口用这个 ID 做去重。这样即使框架层误触发重试也不会造成重复副作用。写在最后的经验我把 agent-skills 这套技能库陆续用在几个 Agent 项目里之后最大的体会是技能描述花费的时间比技能实现还要多。大多数人刚开始都急着写逻辑、调接口真正决定一个 Agent 上限的往往是那些看起来“只是文字”的描述和约束。你花半小时打磨一段 150 字的技能描述可能比花三天优化内部算法更能提升整体任务成功率。另一个意外的收获是技能库天然帮你把散落的业务逻辑沉淀成了“组织的资产”——新同事接手项目时不需要读一堆 Agent 编排代码只看技能清单就能明白系统能做什么、边界在哪里。后续我打算给技能库加上评分反馈机制让模型在每次成功调用后回写一条“这个技能在什么场景好用”的经验记录慢慢让 Agent 形成自己的“手感”。这条路走通的话技能库就不只是一个工具集而会成为 Agent 持续进化的记忆底座。