Agent技能封装：从任务分解到稳定落地的工程化实践

我一直觉得，大模型智能体（Agent）领域现在最缺的，不是更强的基座模型，也不是更花哨的推理框架，而是一套能把“模型能力”变成“可复用生产力”的工程化方法。agent-skills这个名字，就是我在这个方向折腾了大半年后，最想聊透的一个话题。

一句话说清楚它是什么：把智能体经常要执行的复杂任务，像函数一样封装成一个个独立、可复用、可版本管理的“技能”单元。每个技能有明确的触发条件、输入参数、执行步骤和输出规约，智能体接到任务后先做任务分解，再去技能库里检索匹配的技能，按需调用，而不是每次都在上下文中临时推理一套新流程。

这套思路解决的核心痛点，就是“智能体上线容易，稳定工作难”。早期我做的智能体Demo，面对同一个类型的需求，每次生成的步骤都不同，链路一长就开始飘：要么中途漏掉关键校验，要么参数传错，要么生成格式五花八门无法解析。把流程固化成技能之后，才真正实现了“同一个活，十次做出来一个样”。这篇文章面向两类读者：一类是正在做智能体应用落地的开发者，另一类是刚接触智能体开发、想搞清楚“技能”和“插件”“工具”“工作流”到底什么区别的入门者。我会把核心原理、目录设计、触发机制、踩坑经验一次性讲透。

1. 技能到底是什么：先厘清它和插件、工具、工作流的边界

很多人第一次听到“agent-skills”这个概念，第一反应是“这不就是插件吗？”。我当初也这么想，直到被实际项目的复杂度教育了一轮，才搞明白它们之间的边界到底在哪里。

从在智能体系统里的定位来看，工具是原子操作的最小单元。一个工具就是“做个HTTP请求”“读个文件”“执行一段SQL”，它有确定的入参和确定返回，没有任何分支逻辑，连“如果请求失败就重试”这种策略都不该放进工具里。工具解决的是“我能做什么动作”的问题。

插件是工具的集合加一些扩展逻辑。比如一个GitHub插件，内部可能有十几个API调用工具，还可能带一些认证逻辑、数据格式化逻辑。插件解决的是“我能对接哪个外部系统”的问题。

工作流是编排层的产物，它在工具和技能之上，把多个调用步骤用有向图编排起来，有明确的开始节点、结束节点、人工审批节点。工作流解决的是“业务流程怎么走”的问题。

技能则完全不在同一维度上。技能的核心特征有三个：

1. 面向目标而非面向动作：技能描述的不是“调用GitHub获取Issue列表”，而是“完成一个Issue的完整追踪与状态更新闭环”。目标本身可能包含“先查清单、再读取详情、再判断是否需要升级、最后更新标签”这一串动作，内部组合了多少工具调用、有没有条件分支，都是技能内部的事。
2. 策略内聚：技能内部自带决策逻辑。同一个场景下，什么情况下走A分支、什么情况下走B分支，这些规则写在技能内部，而不是每次靠大模型临场发挥。
3. 可被检索和调度：技能有名字、有描述、有参数规约，智能体在接到任务后能通过“技能清单索引”主动匹配。这是它与工作流最大的区别——工作流是被外部引擎强制执行的，而技能是被智能体在运行期动态选择的。

画个简单的对比表，这样最直观：

看完这组对比，再回头看“agent-skills”的设计目标就很清晰了：它要把“模型能力”和“业务经验”深度绑定，让智能体干同一件事的时候，遵循的是沉淀下来的最佳实践，而不是每次撞大运。

1.1 为什么不能把所有逻辑都写进系统提示词里

这是我在早期最常陷入的误区。既然要让智能体稳定执行某类任务，那最简单粗暴的办法就是把要求一条条写进系统提示词，或者在每个用户请求前面拼接一大段“任务执行规范”。

这种做法在小范围实验里确实有效，但随着任务类型变多、执行规范变长，问题会集中爆发。第一是上下文污染，系统提示词被塞进一个并不相关的任务描述时，会干扰模型对当前请求的注意力聚焦。第二是提示词工程的可维护性断裂，需求方每调整一个业务规则，都要把整个提示词从头到尾核对一遍，很容易改出前后矛盾的条款。第三是触发精度失控，模型对所有规则一视同仁，你希望“只在处理退款时校验额度”，但它可能在处理普通订单时也强制要求走额度校验，导致流程卡死。第四是上下文长度压力，技能库如果全部平铺在提示词里，模型每轮都要处理这些token，成本和延迟双双上升。

技能的做法完全不同：提示词里只保留一个短小的“技能路由说明”，每项技能在库里独立维护，需要时把对应技能内容注入当前上下文。也就是说，跟当前任务无关的技能不会占用上下文，模型看到的永远是“当前任务需要的那部分规则”。从时间复杂度的角度看，平铺方式每轮都是O(全部技能长度)，而技能路由方式在理想情况下是O(当前技能长度)，差距非常明显。

这里要特别强调一个容易被忽略的点：技能内容虽然平时不在上下文里，但技能清单索引必须在上下文里。我们知道，智能体的调度引擎需要一个全局视图，才能知道“库里有什么技能可以调用”，所以需要把一份精简的技能清单（技能名+一句话描述+参数摘要）常驻在提示词中。真正的技能正文则按需加载。

2. 技能库的设计：从最小可运行到分层分域

技能库的目录结构是整套方案的地基。早期我做的第一版技能库，就是把所有技能都堆在一个文件夹里，每个技能用一个Markdown文件描述，调用时靠模糊匹配。结果项目规模一大就乱套了：描述相近的技能相互干扰，同名技能在不同域里含义完全不同，模型经常匹配错目标。后来参考了企业内部知识库的分层方式，才逐渐沉淀出下面这套结构。

2.1 目录结构与核心文件定义

整个技能库以仓库形式存在，根目录下按“域”划分一级目录，每个域下面再按“场景”拆分。以代码开发助手的技能库为例：

skills_repo/ ├── agent_skills_index.yaml # 全局索引，触发匹配的核心依据 ├── domains/ │ ├── code_review/ # 域：代码评审 │ │ ├── scene_pr_check/ # 场景：PR检查 │ │ │ ├── SKILL.md # 技能定义主文件 │ │ │ ├── scripts/ │ │ │ │ ├── diff_parser.py │ │ │ │ └── rule_checker.py │ │ │ └── assets/ │ │ │ └── review_template.md │ │ └── scene_refactoring/ # 场景：重构建议 │ │ └── SKILL.md │ └── data_analysis/ # 域：数据分析 │ ├── scene_outlier_detect/ │ │ └── SKILL.md │ └── scene_report_generate/ │ └── SKILL.md └── common/ └── base_utils/ # 跨技能共享的基础能力

每个技能的核心是SKILL.md，它承担两个职能：给人看的技能说明，以及给模型看的执行规约。以下是我实践中验证过比较实用的结构模板：

--- name: scene_pr_check description: 对提交的Pull Request进行自动检查，包括冲突检测、lint校验、测试覆盖评估、关键文件变更风险评估。 trigger_conditions: - 用户要求对PR进行审查 - 用户要求检查合并风险 - 检测到PR状态变更为待审查 input_schema: pr_number: type: integer required: true description: PR编号 base_branch: type: string required: false default: main output_schema: check_result: type: object properties: can_merge: boolean risk_level: string(enum: low/medium/high) issues: array version: 1.3.0 --- ## 执行目标 对PR做四层检查：冲突层、静态层、测试层、变更评估层。最终输出结论和可执行建议。 ## 执行步骤 (必需严格按序执行) 1. 使用 diff_parser 提取变更文件清单和diff摘要 2. 对变更文件执行以下规则检查： - 若包含依赖清单文件，检查依赖版本是否有已知兼容性问题 - 若包含数据库迁移脚本，检查是否存在不可逆操作 - 若删除公共API定义，检查调用方是否同步更新 - 若新增文件超过 500 行，提示拆分 3. 调用 rule_checker 执行lint和测试用例覆盖率校验 4. 根据上述检查结果生成 risk_level ## 分支策略 - 若依赖清单检查发现已知高危漏洞依赖，risk_level 直接设为 high，终止后续检查并立即报告 - 若覆盖率低于 60%，risk_level 设为 medium，不阻断进度但列入必改项 - 其余情况按低风险处理 ## 常见错误与处理 - PR编号不存在：返回错误信息，不执行后续步骤 - diff 解析失败：尝试重试一次，仍失败则上报解析异常

这个结构里有几个关键设计是经过实测验证的：触发条件那一栏要做成“模型友好的匹配关键词”，不能写成长难句，否则全局索引那一步就会出现匹配不着或匹配过宽的问题。输入输出参数必须写完整，尤其是参数的类型、必填性、默认值。分支策略单独拆出来，这是因为我在实践中发现，当你把分支处理混在步骤描述里，模型更容易在长流程中丢失条件判断。

目录结构上还有两个容易忽略的设计考量。第一个是common域，它专门放那些不面向具体业务目标、但被多个技能复用的基础模块。这样做的好处是避免重复实现，更关键的是让每条技能的职责边界更干净。第二个是场景与域的嵌套关系，域是对一类目标领域的分组，场景才是真正会被调度的原子技能。agent_skills_index.yaml索引只登记场景级别的技能，不登记域级别的目录。一开始我把域也写进索引，结果模型经常匹配到域级别，然后“满脸疑惑”不知道下一步该干什么。

2.2 技能描述的写作量级：多少字才算“刚刚好”

技能描述写太长和写太短都是灾难。写太短，模型检索时无法准确判断该技能是否匹配当前需求；写太长，每次加载技能时都要吃掉大量上下文空间，响应速度和成本双双恶化。我探索出的经验是：SKILL.md正文控制在100到200行，前端描述控制在30到60字。

前端描述那几十个字，是整个技能库里最重要的写作对象。因为全局索引只靠它来判断“这段用户请求跟哪个技能相关”。写作时要用“动词+对象+目的”结构，把触发动作说清楚。举个例子，与其写“处理pull request”，不如写“检查PR冲突、lint、覆盖率与变更风险，输出合并风险评估”。前者太泛，模型可能把“我想看看这个PR改了啥”也派给它；后者把边界框死了，命中和不命中的范围都更清晰。

正文部分的每个执行步骤，要写到“模型不需要再推理下一步该怎么办”的程度。判断标准很简单：把步骤给一个不熟悉业务的新同事看，他能不能照着一步步做下来。不能就把步骤再拆细。

3. 调度机制：任务分解、技能检索与参数提取的完整链路

技能库搭建好之后，最核心的运行机制就是调度。完整链路可以拆成四个阶段：任务分解、技能检索、参数提取、执行与验证。这一节我会把每个阶段的实现逻辑和关键参数都展开讲清楚。

3.1 任务分解：识别出“需求片段”和“技能候选集”

当用户输入“帮我看看这个项目的代码质量，顺便把最近一周的提交记录整理成周报”，这个请求看似只有一个任务，实际包含两个技能目标：代码质量检查和提交记录整理。任务分解要做的就是把这个复合请求拆分，识别出需要调用的技能列表。

我在实现里采用了“两轮匹配”的方式。第一轮不直接匹配技能，而是让调度层从请求中提取“任务意图集合”。这个过程本质上是一次轻量级分类，输入是用户请求全文加上系统当前的技能清单索引，输出是候选技能顺序列表。第二轮才真正把候选技能的具体定义加载进来，让模型确定最终调用哪些技能以及每个技能的执行顺序和依赖关系。

这里有个非常关键的工程决策：任务分解这步不能只依赖模型推理，要结合一个小的规则闸门。规则闸门里要提前写死“互斥技能”和“顺序依赖技能”的关系。比如“生成周报”这个技能依赖“提交记录分析”的输出，那无论如何调度顺序都不能倒置；再比如“生成数据报表”和“发送邮件”两个技能在同时触发时，必须等报表技能输出成功后才能调用邮件技能。把这类关系写死在代码里，能跑得比模型推理稳定得多。

3.2 技能检索：全局索引匹配的高性价比方案

技能检索的候选方案里，最简单的是“模型直接遍历技能清单”。这个方案的前提是技能库很小，几十个技能以内可以这么干。一旦超过这个规模，就必须引入向量召回。

我推荐的做法是混合召回：先用关键词规则把所有技能库里trigger_conditions和description中能精确对应到用户请求词的技能拉出来，再用向量检索做召回补充。向量检索主要解决“用户没说关键词，但意图高度匹配”的场景。然后对两路结果做相关性融合，取排名靠前的3到5个技能作为候选集，送入模型进行最终裁决。

候选集为什么取3到5个而不是1个？因为最终裁决需要对比。如果只给模型一个候选，模型没有选择余地，匹配错了也只能硬着头皮执行。给3到5个候选，模型能做相对比较，准确率明显提升。我做过一轮对比实验，同样一个包含50个技能的技能库，单一候选的匹配准确率大约在78%，五候选让模型重新选择后准确率可以提升到92%上下。

为了加深印象，用一个具体的检索样本举例：

用户请求：“帮我检查一下我们这次发布的包依赖有没有漏洞，顺便评估一下测试覆盖率够不够。”

第一轮关键词规则命中：scene_pr_check（因为有“检查”“测试覆盖率”），同时scene_dependency_scan也因为“依赖”“漏洞”被召回。向量召回又补充了scene_security_audit。最终进入模型裁决的候选集有三个：scene_pr_check、scene_dependency_scan、scene_security_audit。模型结合技能描述判断：用户意图是“依赖漏洞”和“测试覆盖率”，而不是“全面PR检查”，所以最终裁决执行scene_dependency_scan，并把test_coverage作为附加检查项。

3.3 参数提取：从用户请求中抽取结构化输入

技能检索完成之后，下一步是把用户请求中的信息映射为技能入参。这一步看似简单，实际是错误高发区。常见问题包括：用户说了参数值但用了非标准表达方式，模型没转成input_schema里声明的类型；用户没说某个必填参数，模型自作聪明填了一个默认值；事实性幻觉，模型把并不存在的参数值编了出来。

我在这块做了三层保护。第一层是定义规约，每个参数都要写清楚“从哪来、是什么类型、怎么转成标准值”。第二层是必填校验，必填参数缺失时不允许直接执行，而是生成追问信息让用户补充。第三层是值域校验，用正则和枚举把范围卡死，超出范围就拒绝执行而不是带病执行。

注意一个反向细节：不要把参数提取做得太“聪明”。有时候模型会在用户没说的情况下，拿着上下文里某个无关信息填进参数，这反而是错误的来源。参数提取的原则是“拿用户说的，推理用户明确表示的，但不编造用户没提的”。

3.4 执行阶段与结果验证：最后的防线一定要硬

执行阶段由代码调度器控制，而不是模型自由发挥。调度器按照SKILL.md声明的步骤列表，一步一步调用脚本或工具。每个步骤的输出会传给下一步作为输入，步骤之间用明文记录传递，方便全链路追踪。

结果验证是很多实现会省略的环节，但它恰恰是最值得投入的部分。我建议在每轮执行后做三样检查：输出格式校验、关键字段非空校验、领域规则校验。输出格式校验是最基本的JSON Schema校验；关键字段非空校验是针对特定技能定制的，比如“周报生成技能”就必须保证report_body字段不为空；领域规则校验是把业务上不可违背的规则写死在验证器里，比如“任何情况下风险评估等级不允许直接从低跳到高”。这套验证在CI阶段和运行阶段都会跑，CI阶段发现问题说明技能库自己的逻辑有漏洞，运行阶段发现问题说明这次输入撞上了边界情况，两者都要记录下来作为后续迭代依据。

执行过程中出现失败时的重试策略也要提前想清楚。我的做法是默认不做自动重试，而是记录详细错误上下文，让用户或上层应用决定是否重试。原因是很多问题不是重试就能解决的，重试只会浪费成本，更关键的是如果错误由参数错配引起，重试一万次都是同样的失败。把失败样本收集起来，定期去优化技能定义和参数提取，比现场重试的价值高得多。

4. 我在真实项目里踩过的坑：三次大规模返工教训

技能方案看上去逻辑清晰，实际落地时坑非常多。我挑了三个对我影响最大的坑展开讲，每个都对应一次真实的大规模返工。想绕过这些坑，直接看我这段总结比自己去踩一遍划算得多。

4.1 技能粒度失控：从“技能库”退化成“工具库”

第一次搭建技能库的时候，我把所有可复用的操作都定义成了技能。比如“读取文件内容”“调用API获取数据”“发送Slack消息”这类原子操作也照单全收，每个都配了独立描述。结果技能库塞进两百多个技能之后，索引变得无比冗长，模型每次匹配的耗时和错误率同时暴涨。

事后复盘意识到，我把“技能”和“工具”的概念混在一起了。读取文件、发消息、调API这些操作粒度太细，它们没有“目标”，只有“动作”。真正能被调度的技能，应该是“用一组工具完成一个有业务价值的闭环目标”。

返工做法：把细粒度操作收编为工具层，不再出现在技能索引里。只有带业务目标定义、带完整步骤编排的单元，才进技能库。重建后的技能数量从两百多个降到五十几个，匹配准确率和执行稳定性同时大幅提升。层面决定治理质量，这个教训值一次返工。

4.2 技能覆盖不足：用户需求频繁落进“技能空白区”

技能库建完后的第一次线上测试，我发现用户的高频需求里有一半技能库覆盖不到。比如用户问“帮我分析一下这个项目的注释质量怎么样”，显然没有对应技能。调度器找不到匹配时，就退化成“常规对话模式”，由模型自由发挥，结果自然不稳定。

这就暴露出一个问题：技能库规划阶段，我一直在“猜测”用户会提什么任务，而不是“统计”用户真实会提什么任务。

返工做法：把所有历史会话记录拉出来做意图聚类，统计出高频前二十的需求类型，逐条确认是否有对应技能。没有的补齐，有的但技能描述跟用户表达习惯差异大的，重写描述以匹配真实高频表达。从那以后我定了一条规矩：技能库的维护节奏不是“开发完就完事”，而是每周根据新会话做增量覆盖复盘。技能库是活的东西，不是一次性交付的静态代码。

4.3 频繁版本变动引发的触发混乱

技能库上线后，业务方经常调整触发条件。一开始我是直接把SKILL.md里的触发条件改掉，完全不做版本管理。结果同一个技能的新旧版本同时存在于缓存的索引和实际技能文件中，模型时而匹配到旧描述，时而匹配到新描述，触发结果飘忽不定。

这个坑本质上是“数据与代码不分家”的治理乱象。解决路径很清晰：给技能库引入严格版本管理，每次变更走“提交-评审-发布”流程。发布不是覆盖文件，而是生成新版本的技能包，索引文件同步指向当前生效版本。系统运行期间只读取已发布版本的快照，不会因为文件被临时编辑而出现“读到一半”的状态。

现在我的技能发布流程大致是这样：

1. 开发分支创建新版本，改SKILL.md和关联脚本
2. 本地跑一遍技能自测用例，确认输入输出符合预期
3. 提交合并请求，触发CI里的验证校验
4. 合并通过后，构建版本快照并更新运行环境索引
5. 运行环境热加载新版本，灰度一小段时间，观察用户请求成功率

5. 进阶设计思路：技能组合编排与团队化运营

基础技能体系跑通之后，我遇到的新问题是：一个真实业务需求往往要串起两三个技能才能完整解决。这个阶段我发现，与其让模型在运行期自由发挥技能组合逻辑，不如把一些高频的“技能链路”也固化下来。

5.1 用“元技能”表达跨领域流程编排

“元技能”这个概念理解起来很简单：它本身不执行具体工具调用，而是定义一组技能的调用顺序和依赖关系。比如一个“完整代码交付检查”的元技能，内部定义的是“先跑依赖扫描，再跑PR检查，再跑测试覆盖率评估，最后生成交付总结”，每个步骤都指向具体技能。元技能有自己的索引条目和描述，但它不含步骤内的工具调用细节。

元技能的价值在于把“编排经验”也沉淀下来，避免模型每次组合技能时都要临时决定顺序和判断条件分支。跑得好的组合，就固化成元技能；组合得不好的，就不会被保留。这是一种从经验到资产的进化路径。

在设计元技能时要注意一个权衡：编排不能拧得过死。基础技能层面保留一定的模型自由裁量空间，应对输入变化；而如果某条链路经过大量实测，步骤和条件完全稳定，就可以整体升级为确定性工作流，由代码引擎强制执行。我的经验是“越稳定越往下沉”，模型能力应对波动，工程能力保证稳定。

5.2 跨团队技能复用与质量控制

当技能库从一个团队扩展到多个团队，新的治理问题就出现了。不同团队对同一业务概念的定义可能不同，比如订单状态字段A团队叫pending，B团队叫awaiting_payment。如果技能库没有统一的领域术语约束，模型匹配出的技能会携带各自团队的口径，下游消费者根本不敢直接使用。

因此跨团队复用必须有集中治理机制。我的做法是成立一个“技能维护小分队”，负责终审所有技能的命名、描述、输入输出规约。技能贡献者不需要自己批准自己的技能，统一走“提交-评审-发布”通道。评审重点看三点：与其他技能有没有命名相似导致的匹配歧义；input_schema字段命名是否符合领域术语标准；描述中的触发词是否符合一线用户的真实表达习惯。

这套治理机制坚持一年下来，最大的收益不是技能质量本身，而是让所有团队对“技能”这个概念建立了共同的心智模型。开发提需求时不再说“帮我写个脚本处理一下”，而是说“这应该做成一个新技能还是扩展现有技能”，讨论质量完全不同。

5.3 技能的评估闭环：用数据代替直觉

最后一个进阶要点是评估闭环。技能好不好，不能靠代码review时看描述顺不顺眼，要看线上数据。我维护了一套技能质量看板，核心指标如下：

每周跑一次数据复盘，重点看三个“率”的异常波动。如果某个技能的用户干预率突然飙升，通常意味着最近的版本改动破坏了边界条件或分支策略；如果参数提取错误率高，往往是用户表达出现了新说法，而技能描述里的触发词没跟上。每周按数据反馈迭代一次技能描述和触发规则，比任何拍脑袋优化都可靠。

6. 给你的第一步实操建议：从零建立一个种子技能

如果你现在完全没做过技能体系，我建议不要一开始就盘算建一个庞大的技能平台，而是先手工建立一个“种子技能”跑通全流程。

我的建议路径是这样的：

1. 挑选一个你日常使用频率最高的智能体任务，比如“整理会议纪要并提取待办事项”
2. 手写一个SKILL.md，包含完整的触发条件、输入输出Schema、执行步骤、分支策略
3. 如果你的智能体框架支持技能目录，就把这个技能放到目录里；如果不支持，就用最粗暴的方式，在每次请求前手动注入这个技能文件
4. 连续用两周，记录它在不同表述下的触发成功率、执行成功率
5. 根据失败记录迭代描述和步骤颗粒度

种子技能跑通之后，你对技能机制的感受会和看书完全不一样。你会开始理解哪些任务适合固化、哪些任务保持模型自由发挥反而更好，也会慢慢找到“技能描述写作”的手感。

我的建议是把技能库的构建当作一个“慢慢长出来”的过程，而不是一次性设计完美再上线。先保证少数几条链路跑得极稳，再逐步扩展覆盖范围。技能库的质量比数量重要得多，50个精品技能一定强过200个形同虚设的占位技能。

我在实际跑这个体系时最深的一点体会是：真正困难的不是写代码，而是定义清楚“什么是稳定的行为标准”，并且肯花时间把每一条链路打磨到所有参与者都放心依赖的程度。智能体的上限，很大程度取决于它背后有没有一套值得信赖的技能底座——这个投入，值得每个做智能体落地的人认真去做。