"agent-skills"这个标题我扫了一眼就知道，不是又一个"调用几个API就算完事"的示例项目，而是想把Agent的能力做成可复用、可管理、可迭代的"技能库"。早期我搞Agent应用时也走过弯路，跟大多数人一样，把所有指令堆进系统提示词，结果提示词膨胀到几千字之后，效果反而断崖式下跌。后来才慢慢悟明白：一个稳定的Agent体系，核心不在于模型本身多聪明，而在于你如何把"会做的事"拆成一个个边界清晰、可独立测试、能按需调用的技能模块。这篇文章就围绕我自己打磨agent-skills整套设计的过程，聊透技能包的目录结构、调用链路的工程细节、测试评估的实操方法，以及几轮踩坑之后沉淀出来的取舍经验。正在搞Agent应用、想摆脱提示词堆叠困境的开发者，应该能从里面拿到可直接抄作业的骨架。
1. 从"提示词堆叠"到"能力模块化"：Agent技能到底解决了什么问题
1.1 提示词膨胀给Agent带来的四类真实问题
先说说我为什么最终转向技能化改造。当时手头一个内部效率Agent的任务说复杂也不算复杂：能查文档、能写周报、能调内部接口查数据、能做简单的日程安排。最初版本逻辑很直接——把这些能力全部描述塞进系统提示词，配合几个function calling的声明。功能确实都跑通了，但用了一段时间问题全冒出来了。
第一是效果衰减。提示词到4000字左右的时候，模型在复杂任务里开始出现"选择性遗忘"，明明定义了五个工具，它可能只会稳定使用其中两三个。第二是维护成本失控。产品提一个新需求，你就要在提示词里再塞一段描述，改一次就要全量回归测试一遍，因为谁都不知道改动会不会影响其他能力。第三是上下文浪费。每次对话都要把全部工具描述传给模型，token消耗直线上升，成本肉眼可见地涨。第四是故障定位难。一个技能出问题，你根本没法单独验证，只能端到端跑整条链路，排查效率极低。
这些问题的本质其实在于：把"能力"和"对话上下文"绑死在了一起。而agent-skills的核心思路，就是把每一项能力做成一个独立模块，平时不进系统提示词，只有真正需要调用时才把对应的技能描述动态注入模型。有点像施工队不再随身带全部工具，而是接到任务单再去工具间按需领取，施工效率自然不一样。
1.2 技能（Skills）在Agent体系中到底管什么
技能这个说法在不同框架里有不同叫法，有的叫plugin，有的叫tool，还有的叫capability。但把它们放在一起对比就会发现，单纯做工具封装和做技能体系之间有明显区别。工具封装往往只关注"能做什么"，而技能体系更关注"什么时候做、怎么做、做错了怎么办"。
在agent-skills的落地里，一个技能包应该包含三层内容：触发条件（什么意图、什么场景下应该调用这个技能）、执行逻辑（具体调用什么API、什么函数、跑什么代码）、失败策略（调用失败后是重试、降级还是返回兜底话术）。这三层缺一不可。光有执行逻辑没有触发条件，模型不知道该在什么时候调它；光有触发条件没有失败策略，运行时的稳定性完全不可控。
我见过不少团队把Agent技能简单理解成"一个函数配一段描述"，这种理解在Demo阶段没问题，但到了生产环境就会频频翻车。举个真实出现的例子，某次内部项目里，Agent需要调用内部工单系统的接口查询任务状态。接口偶尔会返回401鉴权过期，我们的技能没有处理失败策略，结果模型就自作主张跟用户说"系统出错了"，然后直接结束对话。加了失败策略之后，技能会先静默刷新token重试一次，再失败才降级返回提示。
所以技能管的东西其实是"一个完整的、可独立运行的业务能力闭环"，而不仅仅是一次函数调用。
1.3 技能与函数调用、工作流、长时任务的边界划分
很多人在设计技能体系时都会卡在一个问题上：技能和函数调用、技能和工作流、技能和长时任务，边界到底怎么划。我的划分原则很简单粗暴——看"决策点"在哪里。
- 函数调用：层面最低，只执行一个确定操作，入参出参明确，没有决策逻辑。比如按ID查用户信息，这就是函数。
- 技能：比函数高一层的决策单元，可以自行决定内部调用哪个函数、按什么顺序调、要不要重试。比如"根据用户提问搜索内部知识库并总结"，它内部可能要调向量检索，要调文档解析，要调大模型总结，但对外只暴露一个意图出口。
- 工作流：多个技能的有序编排，有明确的步骤依赖和分支判断。比如入职流程，先拉取候选人信息，再生成入职材料，再走审批。
- 长时任务：跨多轮对话、可能需要异步执行的任务，比如"帮我把这份报告定时发给三个团队"，这需要任务持久化，不属于技能范畴。
在我实际设计agent-skills时，我把前两者视为技能内部的事，工作流则通过与技能调度器的组合来实现。这样切分的好处是：每一层都可以独立测试和维护，而不会因为层与层之间耦合过深导致改一处崩一片。
2. 技能包的目录结构与描述规范：先定标准再写代码
2.1 一个最简技能的完整文件清单
进入实操阶段，技能包长什么样？我建议每个技能独立成一个目录，目录内至少包含描述文件、实现文件、参数声明三件套。以我常用的目录结构为例：
skills/ knowledge_search/ SKILL.md run.py schema.json calendar_helper/ SKILL.md run.py schema.json code_review/ SKILL.md run.py schema.jsonSKILL.md用纯文本或轻量标记描述技能的元信息，包含名称、描述、触发场景、示例对话、依赖关系。schema.json描述入参出参结构，供校验和模型格式化使用。run.py是实现技能逻辑的入口，可以是Python脚本、命令行工具、API调用封装等。
初期我也有过一个误区，觉得技能只要写一个函数接一个描述就行，没必要拆文件。直到第一次在某个真实项目里要给技能加单元测试，才发现如果没有独立的schema文件，测试代码根本没法自动化构造入参。后来我干脆把每个技能目录当作一个微型服务来管理，该有的文件一个不少。这看起来多了一点抽象成本，但换来的是后续的自动化能力。
2.2 描述文件里最容易写错的两个字段
SKILL.md里最核心的是description（描述）和trigger_conditions（触发条件）。这两个字段直接决定了模型的调度准确性，但也是大家最容易写废的地方。
先说description的常见问题——写得太长。有人为了"让模型理解得更清楚"，把描述写成了一段三百字的小作文，甚至把实现细节都写进去。实测下来这是授人以柄：描述越长，模型在意图匹配时越容易抓错重点，最后召回了一堆不相干的技能。我的经验是描述控制在三句话以内，第一句话概括"这个技能能干什么"，第二句标出关键能力边界（不干什么），第三句给出典型的用户说法示例。比如：
description: 在内部知识库中检索信息并返回摘要结果 scope: 仅覆盖知识库文档内容，不包含外部互联网搜索 examples: - "帮我查一下报销流程" - "项目上线 checklist 在哪里"再说trigger_conditions。很多人直接复制description，这是纯粹浪费字段。触发条件的意义是帮助路由层快速排除不相关技能，应该以"用户意图"和"上下文信号"为维度，而不是以执行细节为维度。比如搜索技能写触发条件时，要写"用户想查找资料、询问内部规定、寻找文档位置"，而不是写"调用了search API"。一个是面向意图，一个面向实现，前者才是模型和路由层看得懂的信号。
2.3 技能间的依赖与共享上下文设计
技能不是孤立的，往往一个技能内部要调用另一个技能的能力，或者多个技能需要共享某段上下文数据。这个依赖关系如果靠"各技能自己全局查找"来做，很快就会乱。
我采用的设计是显式声明依赖。在SKILL.md里加一个dependencies字段，列出依赖的技能名称和版本约束。调度器在加载技能时先解析依赖图，按拓扑顺序加载。这样不仅加载顺序可控，还能在编译阶段就发现循环依赖，不用等到运行时报错。
共享上下文方面，我维护了一个全局但是有 namespace 的上下文容器。比如当前用户信息、当前项目代号、当前会话时间区，都放在ctx.user、ctx.project、ctx.session这样的命名空间下，技能只能通过显式声明来请求访问，不能直接硬读全局变量。目的依然是控制耦合面，技能内部改坏了不至于把整个共享状态搞脏。
3. 技能注册、检索与执行链路：一次调用是怎么跑通的
3.1 启动时的技能扫描与注册机制
技能库要在项目启动时被自动发现并注册，不能靠手写一个大数组。我手头这套体系的启动流程分四步。
第一步，扫描技能根目录，读取所有子目录下的SKILL.md，校验必填字段和数据格式。字段缺失或者YAML解析失败，直接报错退出。第二步，加载schema.json，注册入参校验规则。第三，解析依赖图，确定加载顺序。第四，把每个技能的可调用入口和执行器实例放进注册中心，注册中心对外提供按名称获取、按意图搜索两类接口。
扫描注册这个环节看着简单，但有一个细节值得强调——技能目录的命名规范。我踩过目录名和技能名不一致的坑。某次上线前，技能名叫meeting_booking，结果目录名我写成了reunite（脑子一热用了西班牙语），注册中心的技能名与目录名对不上，排查了半天。后来我强制目录名必须等于技能名，用lint脚本在CI里检查，不一致就直接构建失败。
3.2 意图路由：如何让大模型准确找到技能
技能装进注册中心之后，下一个关键问题是怎么让模型准确选中它。这步做得好不好，直接决定了整个Agent的靠谱程度。
我先说一种效果一般的做法——把全部技能列表塞给模型让它挑。这在技能少的时候没问题，技能一旦超过20个，模型挑选的准确率就会明显下滑，还会出现"明明有专门技能却选了通用技能"的诡异状况。我在实践中改成了两阶段路由：先做一次轻量召回，再做一次精排。
轻量召回阶段，把每个技能的description、trigger_conditions、examples向量化存进向量库。用户提问来时，先用embedding模型计算query向量，从向量库里召回Top-K个候选技能。这个阶段不追求绝对准确，只求别漏掉真正相关的技能，K值我通常设在5到8。精排阶段，把Top-K技能的完整SKILL.md元信息交给大模型，让它选出最匹配的一个或几个，同时给出理由。精排结果的能接受程度明显比直接硬选高，尤其在技能描述高度相似的时候，模型能看到完整字段和示例，判断依据充分得多。
这个方案比单模型硬选多花一次embedding和一次小模型推理，但换来的是调度准确率和稳定性的明显提升。我在某个模拟项目X里对比测试过，单模型硬选的准确率在71%，两阶段路由可以做到89%，遇到描述相近的技能时差距更大。
3.3 执行器：入参校验、上下文组装与异常捕获
路由确定技能后，进入执行阶段。执行器是技能体系里最容易被轻视的环节，很多人直接在Agent主流程里if-else调用，写起来爽，维护起来痛。
我设计的执行器负责三件固定的事：校验入参、组装上下文、统一异常封装。先讲入参校验。schema.json里定义了每个参数的类型、是否必填、取值范围，执行器在调用技能前先做自动校验，不合法直接返回参数错误，省得技能内部到处写防御。
上下文组装则解决"技能需要哪些外部信息"的问题。我用模板注入的方式，在SKILL.md里声明技能需要从上下文读取哪些键，执行器到对应命名空间里取值并注入到执行环境中。比如会议类技能需要当前用户的时区，写ctx.user.timezone，执行器看到这个声明就去取，取不到就抛错提示配置缺失。
异常捕获方面，我给每个技能的执行器统一包裹了try-except逻辑，异常会被转换成结构化的错误信息返回给上层，而不是直接把Python的堆栈抛给模型。模型拿到结构化错误之后，才能按SKILL.md里预设的失败策略去做下一步决策，比如重试、换技能、或者给用户解释。没有这层封装，模型拿到的是一堆堆栈，基本等于废了。
4. 技能库的测试与评估：不能只靠"看着能跑"
4.1 单技能冒烟测试：用最小用例验证功能闭环
技能体系要稳定，单技能测试是第一道关卡。我在每个技能目录下放一个tests文件夹，里面是最小可执行的冒烟用例。所谓最小用例，就是"仅调用这个技能、用最小数据量、验证核心链路通不通"。
举个例子，做知识库搜索技能时，我准备的冒烟用例是：造一条测试文档，调用技能搜索一个确定存在的关键词，断言返回结果文档ID正确；再搜索一个确定不存在的词，断言返回空结果而不是报错。这两个用例加起来二十行代码，但已经把检索通道、结果解析、异常路径都覆盖了。
冒烟测试跑不跑得过，应该作为技能提交库的门禁。我见过太多"代码看起来没问题"的技能，一上线就出活。原因往往很傻——某个第三方API密钥没配、某个字段名在文档里存在但在代码里改了、或者依赖的另一个技能还没注册。冒烟测试不追求全覆盖，它的定位是快速筛选低级错误，把高级问题留给更完整的测试体系去抓。
4.2 多技能协同场景下的回归陷阱
单技能测试过了不代表整套系统稳了。多技能协同的场景里，最典型的回归陷阱有三种，我列出来给各位参考。
第一种是技能间的调度偏移。新增一个描述很"强势"的技能，可能导致本来正确的路由结果被带偏。比如原来只有一个"周报生成"技能，后来又加了一个"日报生成"，两者描述高度相似，结果一些原本应走周报的query被分去日报了。这类问题单测发现不了，必须靠一组"路由回归用例"来覆盖。
第二种是上下文污染。一个技能执行时向共享上下文里写了额外的键，下一个技能读取同一个键时拿到了被污染的数据。这种问题很难复现，时有时无。应对办法是我在测试环境里对每次会话的上下文做快照，跑完用例后对比前后的键集合，凡是技能没有声明写权限却动了上下文的，直接标红。
第三种是依赖版本漂移。技能A依赖技能B的v1.2，某天B升级到v1.3时改了内部接口语义，A还蒙在鼓里。解决思路是在技能声明依赖时指定版本范围，并在CI里做依赖图比对，发现不兼容就阻止合并。
4.3 技能命中率与维护成本的数据分析
测试之外，评估技能体系的好坏需要量化指标。我在仪表盘上长期盯四个数字：意图识别准确率、技能执行成功率、平均执行轮次、技能代码平均变更频率。
意图识别准确率比较好理解，就是我前面说的两阶段路由中，模型选出的技能是否是正确的那个。技能执行成功率则看技能调用后是否如期返回有效结果，这里要把用户事后反馈纳入统计，不能只看系统自己觉得成没成功。平均执行轮次反映的是效率，如果一个简单的查资料请求，Agent跑了好几轮才定位到技能并执行，多半是路由上下文那块出了问题。技能代码平均变更频率则很有意思——如果一个技能每周都在改，说明当初设计技能的边界就没划好，总在补漏洞，这时候就该考虑重构了。
这些数据累积到一定程度，用来做技能的"淘汰"决策非常有用。一个技能三个月内命中率低于某个阈值、执行成功率又上不来，就该考虑下线或合并，不要因为看着"有用"就留着拖垮整体性能。
5. 落地过程中的关键取舍与踩坑记录
5.1 技能粒度：拆得太碎和拆得太粗都不行
技能拆分的粒度，是设计技能库遇到的最难平衡点。我经历过的典型失败案例有两个方向。
拆得太碎的案例是：把"查天气""查温度""查风力"各做一个技能。头一天觉得自己分得很细，第二天模型调度就开始犯晕，因为这三个技能的description本来就高度重叠，向量召回阶段几乎无法区分，精排阶段模型也只能猜。最后合并成一个"查天气"技能，内部通过参数区分具体查什么，调度立刻稳定了。
拆得太粗的案例则是：一个"处理文件"技能，里面塞了上传、下载、解析、转换、归档五个功能。单测很难写，因为要覆盖的分支太多；每次小改动都要把整个技能重新过一遍全量回归。更麻烦的是大模型路由时，用户说"帮我转格式"和"帮我归档"，映射到同一个技能名，但内部到底走哪个分支根本不可控。
最后我总结出一个可操作的粒度判定标准：一个技能应该对应一个用户可感知的原子意图。"用户可感知的原子意图"的意思是，用户的一句话里，基本上只会表达一个明确的请求目标，你不需要再追问他要做这个还是做那个。按照这个标准，"查天气"是一个原子意图，"查温度再加穿衣建议"就是两个原子意图，应拆成两个技能，让上层用工作流串联。
5.2 如何处理技能间的功能重叠
技能库规模上去之后，功能重叠不可避免。比如查"排期"这个需求，日程技能可以做，工单技能也可以做，知识库技能可能还有一份操作说明。功能重叠一旦出现，路由就开始抖——同一个query，不同的模型版本、不同的上下文，可能命中不同技能。
我的应对方案不是强行砍掉重复功能，而是建立技能优先级表。在注册中心里维护一张表，记录每个重叠场景的首选技能和备选技能。路由精排阶段，如果模型给出的多个候选技能之间存在重叠关系，优先级表会直接指导选择，而不是让模型凭感觉二选一。
另外，我特别建议在技能描述里主动写清边界。前面提过的scope字段就是干这个的。如果我做的搜索技能只搜内部知识库，而另一个技能能搜外部互联网，我会在知识库搜索技能里明写"不包含外部网络内容"，同时在外部搜索技能里写"当用户明确要求查询公开网络信息时使用"。这种显式的相互排除，比让模型自己揣摩高效得多。
5.3 给新技能的准入标准设置"门槛"
技能库不是垃圾桶，什么想法的东西都能往里塞。我后期给团队定了一套新技能的准入checklist，宁可拒绝冲动创新也不让半成品污染主库。
第一条门槛是必须有明确的触发场景。如果连"用户在什么情况下会用到这个技能"都说不清楚，往后基本也只会是路由层的一个噪声。第二条门槛是必须有可运行的冒烟测试，没有测试直接打回，这条是硬性的。第三条门槛是必须做重叠性评审，对照已有技能列出一张功能映射表，说明这个新技能和现有技能的关系是替代、补充还是完全并行。第四条门槛是必须有失败策略，至少写清楚失败后是重试、降级还是给用户解释，不允许裸奔。
这套门槛刚实施时提效很显著。有几个看起来不错的技能想法在评审时就发现跟已有功能重叠严重，直接合并。同时它也在逼项目成员更认真地思考抽象层，而不是被"多一个技能总没坏处"的想法牵着走。
5.4 生产环境最容易忽视的稳定性细节
最后聊几个只有在生产环境里才会暴露的稳定性细节。第一个是超时控制。技能调用外部API时一定要有全局超时，否则一个技能卡住，整个Agent的对话响应都会被拖垮。我给不同技能的默认超时设了上限，涉及网络请求的必须显式设置，比如8秒；纯本地计算的可以放宽到20秒。超过超时的调用要立刻返回错误并触发失败策略，而不是让用户干等。
第二个是技能执行的可观测性。每个技能的执行都要输出结构化日志：路由命中原因、入参快照、出参摘要、耗时、错误码。这套日志在后端排查"为什么这个对话聊着聊着就跑偏了"时，价值不可估量。没有日志的时候，出问题就只能靠灌数据和满屏printf，排查一次要半天起步。
第三个是技能的热更新机制。用Agent的人都很讨厌"改个描述还要重新部署"的体验。我做了技能目录的监听器，检测到SKILL.md文件变化后自动触发重新解析和注册。这个机制配合前文的CI拦截器——本地开发和线上发布都走同一套校验逻辑——体验就很顺滑了。踩过一次坑是某次改了技能描述后没有走热更新，线上还在用旧描述，路由老出错，后来我把"技能变更必须触发reload并打印版本号"这条写进了上线规范。
一些实际操作中的体会
这套agent-skills体系从我最初应急绑定的提示词方案，一路演进到现在的模块化技能库，最深的感受是：Agent工程的复杂度不会消失，它只会从提示词文本里转移出来，转移到结构设计里。早期我把所有逻辑堆进提示词时，问题看似简单，实际每次改动都如履薄冰。技能化之后，表面上看工作量增加了——要写SKILL.md、要写schema、要设计路由、要写测试，但每一项改动都变得可控和可验证了。
如果你正在做一个要长期演进的Agent应用，我建议别等到提示词膨胀到不可收拾再重构。一开始就按技能模块的思维去组织，哪怕步骤多了一点，后面你会在维护和迭代时发觉这笔前期投资非常值得。技能化还有一个额外的好处，就是团队成员之间协作时不再需要去改那段共用的大提示词，每个人维护自己负责的技能包，代码冲突和互相踩踏的概率也大幅下降。先把一个最小技能跑通，再把技能数量加到十几个，你的手感自然就来了。
