刚接触 agent-skills 这个词的时候，我有点不以为然，以为它只是把 Prompt 起了一个更高大上的名字。后来真把一个几万行逻辑的智能体从原型推到生产环境，才发现这块东西是绕不过去的分水岭。所谓 agent-skills，通俗点说，就是给智能体安装的“可复用能力模块”，让它不再只会对着一句话现场发挥，而是能在固定的情境里稳定地完成一件具体的事。这个标题看起来很简单，但它背后牵涉技能怎么设计、怎么拆分、怎么存储、怎么调用、怎么维护，整套流程做不做好，直接决定智能体是玩具还是工具。

这篇文章更适合两类朋友：一类是想把现有大模型应用整理得更工程化的开发者，另一类是已经在做智能体产品、但发现行为不稳定、想引入更规范技能机制的产品经理或技术负责人。我会把我在实际项目中总结出来的设计思路、踩坑记录和排查经验全部整理出来，不保证看完就能成为专家，但至少能让你少走几趟弯路。

1. 先搞清楚：Agent Skills 到底是什么东西

1.1 从“会聊天”到“会干活”的分水岭

在智能体刚开始流行的时候，多数人把大模型当成一个超级聊天机器人，用户问一句，模型答一句。这个状态表面上看很智能，但一旦涉及“连续动作”、“外部工具调用”、“领域规则”这些场景，光靠模型自由发挥完全不够。

我举一个真实例子。当时我想做一个自动整理报销单据的智能体，用户只要拍一张发票照片，它就能提取金额、核对税号、判断是否在报销政策允许范围内，最后生成一条报销记录。如果用纯 Prompt 来写，你会发现三个问题：第一，模型每次提取字段的格式不统一，有时候给 JSON 有时候给表格；第二，政策判断需要读文档，但每次都把政策全文塞进上下文里，成本高、还容易超出窗口；第三，这个流程本身是有状态的，先做 OCR、再校验、再入库，纯靠 Prompt 难以保证步骤不可跳过。

这个场景需要的不是更长的提示词，而是一个打包好的“报销技能”——技能里明确规定了输入是什么、调用哪些工具、按什么顺序执行、输出什么格式、失败时怎么办。这才是 agent-skills 真正解决的问题：让智能体从“自由发挥”变成“结构化执行”。

从我的观察看，现在很多团队已经把技能的思路应用到各种领域。有些叫 Skill，有些叫 Tool，有些叫 Capability，本质都一样：把知识、规则、工具调用和输出规范打包成一个可被智能体按需加载的模块。只要把这个模块定义得足够清晰，智能体就能在被需要的时候精准调用，而不是每次都要从头推理一遍。

1.2 技能和普通 Prompt 的本质区别

很多朋友会问：我写一段非常详细的 Prompt，描述角色、步骤、输出格式，不就是一个技能吗？这个问题我一开始也困惑，直到几次实测翻车之后，我总结出三个核心区别。

第一个区别是可复用性。Prompt 是写在对话里的一段话，它和当前的会话历史绑在一起，换个新的会话就要重新写一遍。真正意义上的技能则是独立存储、独立加载的资源，它可以被同一个智能体在不同的会话中反复调用，可以被多个智能体共享，甚至可以被发布到团队仓库里供其他人自动拉取使用。

第二个区别是组件的完整性。一个合格的技能不止包含描述文本，还包含相关的资源配置。比如技能可能需要调用某个 API、读取某份知识库文档、执行某段固定的代码脚本。这些组件在技能被触发时由系统自动装配，而不是靠模型临场在对话里“想象”出来。技能系统做得好的话，这个过程近乎透明，智能体只负责决定“何时用”，技能框架负责“怎么用”。

第三个区别是可测试性。我可以为核心技能准备几十条测试用例，每次修改技能后，都能一键验证旧功能有没有被破坏。但是纯 Prompt 很难做这样的回归测试，因为每次运行都会受到对话历史、模型版本、随机参数的影响。技能只要定义清晰，执行逻辑就是确定的，测试自然成为可能。

说到底，Prompt 是给模型看的指令，而 Agent Skill 是给智能体用的“外设”。前者更像说话时的语气和分寸，后者更像工具箱里的螺丝刀。螺丝刀该拧哪颗螺丝，由智能体判断，但螺丝刀长什么样、能承受多大扭矩，由技能本身决定。这个区分一旦想通，后面的设计思路就顺了。

2. 一个可用技能的设计骨架：从意图到验收

2.1 六个核心要素，一个都不能少

我在实践里总结了一个“技能设计六要素”，凡是缺少其中一项，技能上线后大概率要返工。这六个要素分别是：触发条件、输入参数、执行步骤、所需资源、输出格式、异常回退。

触发条件解决的是“什么时候用这个技能”。它通常是一段语义描述，告诉智能体什么场景下应该选择这个技能。这个描述要足够具体，避免和其他技能混淆。比如“查天气技能”的触发条件不能只写“当用户想知道天气时”，要补充到“当用户询问某个具体地点在某个时间段的天气，且需要一个确定性答案时”。只有触发条件足够窄，技能路由才准确。

输入参数解决的是“用户要提供什么信息”。一个好的参数定义会区分必填项和选填项。比如天气技能必填地点，时间选填，若为空默认当天。定义参数时还要考虑类型、取值范围的约束。我曾经遇到过一个技能，参数定义里只写了“日期”，结果模型把“明天”“后天”“下周一”都传进去，最后技能收到一堆中文相对日期没法解析。后来我在参数定义中增加了“convert_to_absolute_date”的说明和示例，并且要求模型在调用前先进行时间归一化转换，问题瞬间解决。

执行步骤是技能的核心逻辑，也是大多数人最容易写成散文的地方。我的建议是步骤描述必须用编号列表列出，并且要明确每一步的输出结果。如果一个步骤依赖上一步的输出，一定要显式说明。比如报销技能的第一步是“从图片中提取发票信息，输出为 JSON 对象”，第二步是“读取 JSON 中的 total_amount 字段，与报销政策中的限额比较”，每一个步骤都是可执行、可验证的单位。

所需资源包括外部 API 的访问密钥、知识库查询入口、固定的代码片段或配置文件。这些资源不应该被临时写在某个步骤里，而是作为技能的 attachment 一并管理。我见过最好的做法是给资源一个唯一标识符，技能执行时通过标识符去资源中心动态加载。这样如果 API 升级了，只需在资源中心同步更新一次，所有引用该资源的技能都不会受影响。

输出格式决定最终结果如何呈现。对智能体来说，输出最好是结构化的 JSON 或 YAML，这样后续链路可以继续处理。对用户来说，输出还需要有一段自然语言解释。我一般会把两者拆开：“机器可读结果”和“用户可读摘要”。人机各取所需，避免模型为了迎合用户而把数据改得乱七八糟。

异常回退是新手最容易忽略的。技能执行过程中必然出现识别失败、网络超时、数据缺失等情况。没有回退机制，智能体就会僵在那里，甚至给出一个瞎编的答案。我的方案是给每一步定义失败时的降级策略：降级到简化逻辑、请求用户补充信息、或者返回一个明确错误码。后续我在项目管理中，甚至把异常回退写成了技能验收的一项硬性指标，没有回退路径的直接不通过。

2.2 选“技能粒度”的经验

技能粒度是一个非常微妙的问题。拆得太细，智能体决策负担上升，而且容易选错技能；拆得太粗，技能内部又堆了一堆条件分支，慢慢变成“祖传代码”。

我自己的经验是：技能粒度尽量贴合一个“有明确目标的最小完整过程”。何谓最小完整过程？就是用户从发起请求到得到满意结果的整个过程不可再分。比如“订酒店”是一个完整过程，“查找酒店”则只是其中一步。如果你的技能拆到“获取参数”这种级别，那就过度细化了。

实际操作时，我习惯先把一整个业务场景的流程图画出来，找到几个真正独立的产出物。比如制作会议纪要是独立产出物，它可能依赖语音转写、议题识别这些“内部步骤”。那么我只会做一个“会议纪要生成技能”，内部调用两个子技能，而不是把语音转写做成一个独立技能。为什么？因为用户不会单独对智能体说“帮我做语音转写”，他只会说“帮我把今天下午的会议纪要整理出来”。如果技能对外暴露的接口和用户意图不匹配，触发就会失败。

不过有两类子技能我建议单列。第一类是跨场景通用的工具型技能，比如“日期解析”“URL 抓取”“编号生成”，这些技能没有业务背景，任何技能都能复用。第二类是强领域规则型技能，比如“发票验证”“政策匹配”，它们天然是独立模块，做拆分后即使主流程调整，它们也可以作为独立服务存在。

我见过一个项目把所有技能都做成“巨无霸”，一个技能下面挂了几十段逻辑分支。结果模型经常触发错技能，因为触发条件描述根本覆盖不了那么多情况。后来我们把技能拆成十几个小模块，并建立了技能路由表，准确率直线上升。这件事让我更坚定：粒度宁小勿大，但也不要小到失去业务语义。

3. 技能仓库的搭建与管理：我踩过的几个坑

3.1 如何组织目录结构

技能数量少的时候，怎么组织都无所谓。但当技能数量超过二十个，没有清晰的目录结构就是灾难。我初期把所有技能都塞在一个文件夹里，文件名类似 skill_order_v1.yaml、skill_order_v2_final.yaml，结果后期根本不知道哪个是当前生效版本，也容易误加载废弃技能。

后来我参考优秀开源项目的做法，重新设计了目录结构。每个技能独立成一个目录，目录名就是技能 ID。技能目录内部采用统一布局：

• manifest.yaml：保存技能的元信息，包括名称、ID、版本号、作者、描述、触发条件、依赖资源列表。
• prompt.md：保存给模型看的技能指令文本，也就是技能的操作手册。
• resources/：存放技能运行所需的额外文件，比如固定脚本、规则模板、示例数据。
• tests/：存放测试用例，包括输入、预期输出、通过条件。
• CHANGELOG.md：记录每次版本的变更内容。

这个结构的好处是“以技能为中心”，所有关联内容都聚在一起，无论是审阅、测试还是发布都能一步到位。并且这个结构与人认知系统非常契合，人类以自己的记忆模块为中心组织经验，技能系统同样不应将指令、依赖、测试四散在仓库里。

在目录命名上，我强烈建议统一使用小写加中划线，比如 skill-invoice-verify、skill-date-parse。带来的好处是跨平台、大小写敏感的环境下不会出问题，同时避免团队里出现“InvoiceVerify”和“invoice_verify”两份并存的情况。

3.2 版本控制和命名规范

版本控制是技能系统能否长期演进的关键。如果不做版本管理，某次改动把旧技能弄坏了，你可能只能回滚整个系统。我现在给每个技能都维护了一个语义化版本号，格式为主版本号.次版本号.修订号。主版本号在触发条件或输入输出格式发生破坏性变更时加一；次版本号在新增功能且向后兼容时加一；修订号在修复小 bug、优化措辞时加一。

这个语义化规则对我们的意义在于，让智能体路由模块可以准确判断技能是否兼容当前场景。比如某个 Agent 依赖技能版本必须大于等于 2.1.0，如果仓库里只有 2.0.9，路由就不应该把这个技能推荐给该 Agent。我在实际项目中就遇到过版本未匹配导致 Agent 调用了过期技能，最终输出格式与下游系统期望值不匹配的情况。所谓双端解耦，就是这个版本协议的价值。

命名规范同样要强制。技能 ID 一旦建立，就不要随便改，因为所有依赖关系都会引用它。如果实在要改，必须走“弃用”流程：保留旧 ID，新增新 ID，迁移期结束后再清理。清理时还要在 CHANGELOG 里记录清楚，避免后续排查问题变成考古。

我踩过最大的坑是在技能之间互相调用时，直接硬编码对方的 ID 和路径。后来某个技能文件夹被重构，路径变了，调用技能全都挂掉。现在我在资源配置里建议统一使用技能 ID 加版本约束进行声明，绝不直接写路径。这个改动一开始会增加一些配置成本，但后续迁移、扩展、灰度都变得非常顺滑。

3.3 仓库元数据与依赖锁定的做法

这部分是很多团队容易忽视的。当 Agent 项目需要可复现时，仅记录每个技能 ID 是不够的。如果技能依赖的模型版本、API 版本、资源文件版本发生了变化，同样的输入可能产生完全不同的结果。

为此我借鉴了代码项目的依赖锁定机制，为每个 Agent 项目维护一个 lock 文件，记录该项目引用的每个技能的精确版本、资源标识符以及其运行时环境。这个 lock 文件在部署时随项目打包，运行时所有加载动作都基于这份锁定信息。这样即使一周后技能仓库又更新了十几次，测试环境和生产环境拿到的技能版本也完全相同。

我还为每个技能增加了“环境标签”，标记它适合在哪种场景下运行：比如 low-latency 环境、offline 环境、privacy-safe 环境。这项信息在技能路由时会被检查，避免在隐私敏感场景下调用需要外部上传数据的技能。早期没有这个机制，有个技能因为内部调用了第三方 OCR，差点把用户敏感数据传到外部。后来所有这些技能都加了 privacy-safe: false 的标签，才从机制上堵住这个隐患。

4. 实测：让技能真正稳定跑起来的关键

4.1 多轮调用时的上下文隔离

技能在单次调用中表现良好不算本事，真正麻烦的是它在多轮对话中被反复调用。你会遇到一个问题：上一轮技能产生的中间数据污染了这一轮的判断。

举个我实际遇到的例子。一个“购物比价”技能第一轮搜索了“iPhone 15”，生成了搜索结果列表。第二轮用户问“那安卓的呢”，Agent 本应发起一个新查询，但因为上一轮技能残留的变量干扰了上下文，模型误以为“安卓”是对上轮结果的筛选，最终返回了空结果。

解决办法是给技能执行设置“沙箱上下文”。每次技能调用开始前，框架主动清理上一轮注入到会话中的技能专用变量；调用结束后，只把规范的输出结果写回主对话。这样主对话只保留用户和 Agent 的高层语义，不会被子系统的脏数据侵蚀。

我当时实现了一个简单但有效的方式：技能输入输出都经过一个“标准化信封”。信封里有 header 和 payload，header 存放调用 ID、时间戳、版本号，payload 存放业务数据。主对话和技能之间只允许传递信封，谁也不允许直接读写对方的全局变量。这个设计带来了额外的好处：日志里可以清晰地追溯每一次技能调用的全链路，排查问题时不用靠猜。

4.2 错误处理与回退策略

实践中最容易翻车的，不是技能逻辑本身，而是技能执行到一半报错后，Agent 怎么处理。如果只是把错误信息原样抛给用户，体验极差；如果模型自动捏造一个成功结果，危害更大。

我的做法是给技能定义三层错误处理结构。第一层是局部重试：对于网络超时、临时性错误，技能内部自动重试两到三次，每次退避等待；第二层是降级：如果重试失败，则打开一条降级路径，比如从实时接口切换到缓存数据，从精确操作转换为近似操作，并在输出中明确标注数据来源或可信度；第三层是显式失败：当降级也不可行时，技能返回一个结构化错误对象，包含错误码、可读原因和建议动作。

这里最关键的是要让 Agent 明白“显式失败比编造成功更安全”。我会在技能指令里写下这样的规矩：如果你收到 error 标记的返回对象，你必须向用户说明遇到了什么问题，并提出可行的替代方案。绝对不能因为它看起来像是技能失败，就开始自我发挥、编造一个看似合理的答案。

我还遇到过一种情况：技能步骤之间的依赖关系没有被显式声明，导致第 3 步在第 2 步失败后依然执行，结果异常数据一路向后传。后来我要求每个技能在执行步骤定义中明确标注 fail-fast 标签。一旦主路径的必需步骤失败，流程立刻停止，不会继续做无谓的“救火”。

4.3 用测试用例倒逼技能质量

技能上线之前，我会先写测试用例，而不是先写实现。这个习惯是从传统软件工程里搬过来的，但在智能体领域同样有效，甚至更加有效。

我准备了一组固定测试集，覆盖典型正常路径、边界输入、缺失参数、冲突意图和恶意输入。比如价格比较技能必须测试“用户给出了两个不同的货币单位”的情况；报销技能必须测试“发票金额超过政策上限”的边界；日历技能必测“用户说下周五”且今天已经是周五的歧义。

有了测试集之后，我在更新技能时不用再凭感觉判断改得好不好。直接跑一遍回归测试，通过率下来了，就说明新改动稳了。现在不少技能系统也都开始支持 error-message 断言、输出 JSON Schema 校验、甚至让另一个模型扮演“用户”做自动评估。我和团队的实践经验是：哪怕用最原始的方法，也一定要让测试先跑起来，再慢慢加自动化。

4.4 性能与成本的平衡技巧

技能系统如果做得不好，很容易让成本翻倍。最典型的例子是：技能里每一步都调用大模型，导致一次请求烧掉十几次 token。

我自己会把技能步骤分成“需要模型推理”和“不需要模型推理”两类。能靠代码、规则、模板解决的问题，决不让模型插手。比如日期规范化、金额单位换算、编号校验，这些都用确定性代码实现；只有意图判断、语义抽取、摘要生成这些环节才真正需要模型。

另外我给所有外部模型调用设了超时时间和最大重试次数。因为技能内部一旦出现死循环，不限制调用数就会无限烧钱。我在日志里排查过一单异常请求，发现某个技能因为参数解析错误反复调用模型八次，每次都是同一个失败结果。加了调用次数上限之后，这类问题再没发生过。

还有一个节省成本的小窍门：技能执行过程中如果只需要一个 JSON 结果，就尽量用低温度参数并限制 max_tokens。很多技能的任务并不需要创造性，用高温度反而会引入不可控的乱随机性。我把这些配置写进技能资源配置表中，不同技能有不同的推理参数，实测下来成本和稳定性都明显改善。

5. 常见问题速查与个人心得

5.1 高频问题速查表

每个项目踩的问题都有共性，我整理了一份高频问题对照表，方便你遇到相似现象时快速定位：

这张表只是起点。真正科学的做法是建立一套技能运行监控看板，记录每次调用的触发率、成功率、平均运行时长、 token 消耗，以及每个失败分支的分布情况。只有把这些数据拿到手里，迭代才会有方向。

5.2 我在后期会继续扩展的方向

技能系统的边界比大多数人想象的要大。目前我在项目里已经能把“买点菜”这种简单任务拆成“选择菜品—查询库存—生成采购清单”三个子技能做组合调用，但这只是很浅层的编排。下一步我想重点做几个方向的扩展。

第一是技能间的动态编排。现在的实现基本靠 Agent 的语义理解来选择技能，偶尔先调用一个技能，再根据结果去调用另一个。但这种编排是脆的，缺乏严格的状态机。我准备尝试把部分常规范式流程定义成显式的工作流模板，让技能编排也可以像填表一样走官方路径。

第二是技能的安全边界。之前已经遇到过隐私数据外泄的隐患，未来我想深化“数据类别标签”体系。让每个技能声明它可以处理的数据敏感级别，Agent 在路由时自动匹配，敏感任务绝不能走第三方服务。这一步做成之后，整个技能系统才能从“可用”走向“可信”。

第三是技能的自动评估。我现在会手动维护测试用例，但技能数量膨胀之后，手动维护很快就会成为瓶颈。我计划引入一个自动评估框架，让测试集可以按版本自动生成、自动扩充，并支持在 CI 流程里跑模型评测。到那时，技能的每一次提交都能获得质量分和回归报告，上线前就是完全无脑操作。

这些方向未必适合所有团队，但如果你也一样正在长期维护智能体产品，我的建议是趁早把技能的问题当成产品问题，而不是模型提示词技巧。技能一旦沉淀下来，就是团队的核心资产；技能如果只躺在某个文件夹里当摆设，它永远只是一堆没有生命的文字。

我在实际操盘中最大的体会是：不要把 Agent Skills 当作一个花哨的概念，而是当成一套软件工程的标准。它需要设计、测试、版本管理、监控和灰度，缺一不可。如果你现在只是在一堆 Prompt 里挣扎，不妨先挑一个高频需求，把它做成第一个正式技能，把六要素补齐，跑通一次完整的测试与部署。做到这一步，你会发现后面的路一下就清晰了。