Agent Skill 是什么？概念、架构与开发指南

要说今年最热的技术方向，Agent Skill 绝对排得上号。我最早接触这个概念的时候也困惑过——它和 Tool、Function Calling、Prompt 这些词到底什么关系？为什么大家都在折腾它？后来陆陆续续做了几个基于大模型 Agent 的项目，踩了一堆坑，才慢慢明白这个东西的本质。今天这篇就好好聊聊 Agent Skill 到底是什么、内部架构怎么设计、以及真正动手开发一个 Skill 的完整流程和避坑经验。

先说结论：Agent Skill 本质上是把大模型 Agent 的某种“能力”封装成一个可复用、可组合、可独立开发维护的单元。它不是简单的一段提示词，也不是一个函数调用，而是介于两者之间的一套完整能力模块。它的核心价值在于，让 Agent 不再只是“会聊天”，而是真正“会做事”。

这篇文章适合谁？适合正在搭建业务型 Agent、想让 Agent 完成多步骤复杂任务、或者在设计企业级 AI 应用架构的工程师和架构师。看完你至少能搞清楚三件事：Skill 的边界到底划在哪里、一个 Skill 的架构长什么样、以及从零开发一个 Skill 的正确姿势。

1. Agent Skill 概念拆解：它到底是什么

1.1 Skill 的起源：从单次调用到能力封装

要理解 Skill，得先看 Agent 的演化过程。早期的大模型应用就是简单的 Prompt 问答，你问一句，模型答一句，再高级一点就是套个 RAG 让它查资料。那时候所谓“能力”，就是 Prompt 够不够好。

后来出现了 Function Calling，模型可以决定调用哪个外部函数来获取数据或执行操作。这是一个巨大的进步，但问题也随之而来：一个函数顶多干一件具体的事，比如查天气、发邮件、算个运费。当你需要 Agent 完成“帮用户制定旅游计划并预订所有服务”这种复合型任务时，用 Function Calling 去拼，代码会变得极其臃肿，而且逻辑全散落在调用层，根本没法维护。

Skill 就是在这个背景下出现的。它把一系列相关的操作、决策逻辑、甚至子任务组合在一起，形成一个“技能包”。Agent 只需要判断“当前任务需要这个技能”，然后调用整个 Skill，而不是去拼几十个函数调用。最典型的例子就是 Claude 的 Agent Skills 规范，OpenAI 那边后来也在推类似的能力标准化，LangChain、CrewAI 这些框架里也都有对应概念，只是名字和实现方式略有差异。

1.2 Skill 与 Tool、Prompt、Workflow 的核心区别

我经常被问到一个问题：Skill 和 Tool 有什么区别？说实话一开始我也分不太清。后来我用一个很朴素的类比才搞定这件事：

Tool 是“零件”，Skill 是“工序”。零件单个拿出来也能用，但只有组装成工序，才能完成一件完整的产品。比如“发送HTTP请求”是一个 Tool，“调用支付接口完成订单支付”是一个 Skill。支付 Skill 内部可能要校验参数、加密签名、调用支付 Tool、处理回调、更新订单状态，这一整套流程才是 Skill。

同样，Skill 和 Prompt 的区别更明显。Prompt 只是文本，它告诉模型“该怎么做”，但模型可能发挥不稳定，上下文一长就丢指令。Skill 则是一段可执行、可验证的逻辑单元，它可以包含代码块、决策分支、错误处理，以及调用其他 Tool 和子 Skill 的能力。

再说 Skill 和 Workflow 的区别。Workflow 是预设好的固定流程，从头到尾顺序执行，中间不允许偏离。Skill 则是更有弹性的能力模块，Agent 可以在运行时决定怎么用、用多大程度、甚至和其他 Skill 组合。如果说 Workflow 是铁路时刻表，那 Skill 更像是网约车司机——目的地明确，但路线可以实时调整。

1.3 Skill 适合解决什么类型的问题

不是所有东西都需要做成 Skill。我总结了几条判断标准：

一是任务必须有边界。像是“润色文本”“生成周报提纲”这种范围清晰的事，适合做成 Skill。但如果你的任务是“理解这个行业并给出战略建议”，这种边界太模糊，不适合封装成 Skill，因为它没法定义清晰的输入输出契约。

二是任务需要多步骤、多条件分支，或者需要调用外部资源。纯文本生成的任务靠 Prompt 就够，做成 Skill 反而是过度设计。但任务涉及查询数据库、调用 API、读写文件，或者需要在多个候选方案中做决策判断时，Skill 就派上用场了。

三是任务需要复用。同样的逻辑会有多个场景用到，才值得封装。如果你的项目里某个功能只出现一次，我建议先别抽象，直接写在代码里，等第二次需要时再抽成 Skill 也不迟。我在项目里吃过不少“过早抽象”的亏，Skill 数量暴涨但每个都很鸡肋，维护成本反而上去了。

2. 架构设计：一个标准 Agent Skill 长什么样

2.1 总体分层：调度层、执行层、资源层的职责划分

一个设计良好的 Skill 架构，我习惯把它分成三层来看。

最上层是调度层，也就是 Agent Core。它不关心 Skill 内部怎么实现，只负责三件事：识别当前任务适合哪个 Skill、将任务的上下文映射为 Skill 的输入参数、以及把 Skill 返回的结果转换成对话或后续动作。这一层的核心是一个“路由决策器”，通常靠模型能力来做语义匹配，也可以配合关键词规则做兜底。

中间层是执行层，也就是 Skill 本体。每个 Skill 在这里是一个独立模块，内部包含入口校验、逻辑处理、分支决策和结果格式化。执行层的关键是“可插拔”——所有 Skill 实现统一接口，Agent 侧不需要感知每个 Skill 的差异。

底层是资源层，包括模型服务、外部 API、数据库、文件系统、向量库等等。Skill 在执行过程中会按需访问这些资源。合理的设计里，Skill 不直接连接资源，而是通过一个网关层做中转，目的是方便做权限控制、日志审计和限流。

Agent Core（调度层） ↓ 标准协议 Skill Registry（技能注册中心） ↓ 路由分发 各个 Skill 实现（执行层） ↓ 资源网关 Model / API / DB / FS（资源层）

这套分层的好处有三个：一是改动隔离，替换某个 Skill 的内部实现不影响其他模块；二是权限清晰，每个 Skill 可以单独配置能访问哪些资源；三是可观测性，每一层都能独立打日志和监控。

2.2 接口契约设计：输入、输出、错误码的规范化

我见过太多失败的 Skill 项目，死因几乎都是接口契约没设计好。Skill 的输入输出一定要结构化、严格校验，不能像普通函数那样松松垮垮。

输入侧，每个 Skill 都要有明确的参数 schema。不要只定义“参数名”和“类型”，还要加上范围约束、必选可选标记、以及参数之间的依赖关系。比如一个“生成数据分析报告”的 Skill，数据源路径和数据切分粒度这两个参数就有依赖——切分粒度只有在数据源是明细表时才有意义。这种关系不加约束，模型在调用时就容易瞎传参。

输出侧，要统一包装成固定格式。我最常用的是这样的结构：做了没、结果在哪、下一步怎么走。前两项很多人会写，但“下一步怎么走”特别容易被忽略。Agent 拿到 Skill 结果后，需要判断是继续执行下一个动作还是收尾，这个判断的依据就是 Skill 输出的下一步指令提示。

错误码设计也很关键。不要只返回“失败”两个字，要有细分：是参数不合法、资源不存在、外部服务超时，还是内部逻辑异常。不同错误类型对应不同处理策略——参数问题可以让 Agent 重新理解任务，服务超时可以自动重试，逻辑异常则需要告警人工介入。

2.3 状态管理与上下文传递：无状态原则和会话隔离

Skill 设计中最容易翻车的，就是状态管理。

我的建议是：默认所有 Skill 都是无状态的。也就是说，Skill 内部不保存任何涉及具体会话的数据，需要的上下文全部通过输入参数传入。这样做的直接好处是并发安全——同一个 Skill 实例同时处理多个会话时，不会出现变量互相污染的问题。

但在真实场景里，有些任务是天然有状态的，比如“持续收集用户偏好，每次推荐都更准确”。这种场景我建议把状态外置，存在 Redis 或者向量数据库里，Skill 以 session_id 为 key 读写外部状态。Skill 本身依然是“无状态”的，它只是搭载了一个状态读写工具。

上下文传递方面要注意 Token 膨胀。很多 Skill 在第一个版本会不顾一切地把所有历史信息全塞给模型，结果上下文越来越长，价格越来越贵。正确做法是过滤——只传当前任务需要的字段。比如你有一个“客户画像生成” Skill，输入只需用户最近十次交互行为和画像标签，把那些无关的系统日志全部丢掉。我在实际项目中做过对比，上下文裁剪后，不仅成本降了 30% 以上，模型响应质量反而更高了。

2.4 Skill 的组合与编排机制

单个 Skill 能解决单点问题，真正体现 Agent 威力的场景需要多个 Skill 协同。

Skill 的组合大致有四种模式。第一种是顺序执行，前面 Skill 的结果直接作为后面 Skill 的输入，比如“解析简历”之后接“匹配职位要求”。第二种是条件分支，Agent 根据对话内容动态决定走哪个 Skill，比如用户说退换货走售后流程 Skill，说查物流走物流跟踪 Skill。第三种是并行执行，多个 Skill 互不依赖时同时跑，比如做竞品分析时，价格采集、评论抓取、功能对比三个 Skill 同时进行，最后汇总。第四种是嵌套调用，一个 Skill 内部调用另一个 Skill，比如“撰写市场报告” Skill 调“数据统计” Skill 和“图表生成” Skill。

组合方式的选型指南：顺序执行适合流程固定的场景；条件分支适合需求多样、但每条路径清晰的场景；并行执行最大收益在响应速度；嵌套调用适合复杂大任务逐层拆分。没有哪个方案绝对好，核心原则是“组合的耦合度要低”——Skill 之间只能通过输出传递数据，不要直接读对方内部状态。

3. 开发指南：从零构建一个可用的 Agent Skill

3.1 需求拆解与 Skill 边界定义

动手写代码之前，第一件事是把需求拆清楚，定义 Skill 的边界。

拿“智能简历筛选”来举例。你接到一个需求：让 Agent 帮 HR 筛选应聘简历。如果把所有动作塞进一个 Skill，这个 Skill 会非常臃肿——要解析简历格式、要判断匹配度、要生成筛选意见、可能还要自动发邮件通知候选人。正确做法是拆成四个 Skill：简历解析 Skill、岗位匹配度评估 Skill、筛选决策 Skill、通知发送 Skill。

拆分的判断标准有三个：是否有独立输入输出、是否有独立维护的合理性、是否会被其他场景单独调用。简历解析 Skill 可能不仅服务于筛选场景，还可以服务于人才库建设，这就是值得拆出来的信号。

定义完边界后，要给每个 Skill 写一段“能力描述”。这段描述不是给人看的，是给 Agent 的调度大脑看的。写不好描述，Agent 就不知道该在什么时候使用这个 Skill。我见过太多例子，Skill 写得很厉害，但描述写得太模糊，结果 Agent 每次都选错技能。比如你写“这个技能可以处理简历”，就太笼统。要写到“当用户上传简历文件或提供简历文本，需要提取候选人的教育背景、工作经历、技能标签时使用本技能”。

3.2 输入输出契约与处理逻辑实现

定义契约这一节，我用一个实际开发过的“情绪分析 + 应答策略生成” Skill 来说明。

输入参数设计：

{ "user_text": { "type": "string", "required": true, "max_length": 5000, "description": "用户输入的原始文本" }, "analysis_depth": { "type": "string", "enum": ["basic", "advanced"], "default": "basic", "description": "basic只输出情绪类别，advanced额外输出情绪强度和建议动作" }, "history": { "type": "array", "items": {"type": "string"}, "required": false, "max_items": 20, "description": "最近几轮对话历史，用于辅助判断" } }

输出结构：

{ "success": true, "emotion_category": "frustrated", "emotion_score": 0.82, "suggested_strategy": "apologize_and_explain", "response_draft": "非常抱歉给您带来不便，我们马上核查您的问题……", "next_steps": ["verify_order_status", "offer_compensation"] }

其中 next_steps 字段特别关键，它告诉调度层，处理完当前输入后，后面可以考虑执行哪些动作。这种输出设计能让 Agent 的自然衔接性大幅提升，不会出现答完一句就愣住、不知道该干嘛的情况。

处理逻辑上，最核心的决策点是：这个 Skill 的核心步骤到底用模型来推理，还是用代码来硬算。我的经验法则很简单——涉及开放性理解、生成和复杂语义判断的用模型；涉及确定性的数据处理、校验、计算则写代码。举个例子，从文本里提取日期，直接正则就能搞定，没必要把这种操作喂给大模型。你会发现，把非必要的大模型调用砍掉之后，Skill 的响应速度和稳定性都有极大提升。

3.3 元数据注册与调用触发机制

Skill 写完之后要注册到 Agent 的“技能库”里，这一步的细节决定了 Agent 能不能找到你的 Skill。

注册信息至少包含四个部分：名称、描述、参数说明、触发示例。名称要短且语义唯一，方便模型引用；描述在前面说过了，要写清楚“什么场景下用”；参数说明直接复用契约定义；触发示例这个字段很多人不写，但我觉得非常有用。给模型提供三到五个典型的用户话术作为调用示例，能显著降低误调用的概率。比如你的 Skill 是查物流的，可以写示例“我的包裹到哪了”“快递动了没”“什么时候能送到”。模型看到这些示例，匹配率会高很多。

技能注册的方式，项目早期可以直接用一个 JSON 数组存在代码里，方便调试。到了几十个 Skill 以上、多服务协同的场景，需要上注册中心，用数据库存储并提供一个查询接口，Agent 启动时拉取最新的技能清单。

调用触发这块，还有一个常见误区：试图把所有触发逻辑都交给模型判断。模型判断自然语言能力强，但你需要在入口加一层快速过滤器——通过正则或关键词先排除明显不该触发的请求，降低模型无谓判断的次数。举个例子，查物流的 Skill，可以先用正则匹配是否包含“快递/包裹/物流/运单”这些词，匹配不到就直接跳过模型判断，这样既省钱又省时间。

3.4 参数与执行策略的设置原则

参数配置是实操中最有学问的部分，我分享一下几个关键参数的设置经验。

temperature 这个参数一定要看任务类型来调。涉及事实提取、代码生成、数据转换这类任务，我的建议是调到 0.1 以下，甚至可以设 0，因为你希望输出是确定性的。但涉及创意生成、文案润色、头脑风暴这类任务，可以放到 0.7 以上。很多人不管三七二十一到哪都用 0.7，结果做数据提取时模型偶尔编一个字段名出来，排查半天才发现是参数的问题。

max_tokens 设置要有余量但别浪费。有些 Skill 的输出要组装成 JSON 给后续程序使用，如果 output 长度不够导致 JSON 被截断，整个调用链都崩了。我的做法是：根据经验值给最大长度，然后输出的内容严格要求按 JSON 格式化，并加上“must not include any other text”这类约束。

重试策略上，外部 API 调用建议采用“指数退避 + 抖动”的方式。第一次失败等 1 秒重试，第二次等 2 秒，第三次等 4 秒，最多重试三次，同时在每次等待时间上加上随机抖动，防止多个实例同时重试造成流量峰值。重试也要注意只对“可重试错误”生效——5xx 服务端错误、超时可以重试，4xx 参数错误重试也没用，纯浪费。

3.5 完整实操演示：开发一个“日报生成” Skill

这一节我用一个完整的“日报生成” Skill 演示整个开发过程，你可以直接照着做。

需求描述：员工在每天下班前，把今天的任务完成、明日计划、风险问题用结构化方式提交，由 Skill 自动生成一份格式规范的日报。这个需求适合做成 Skill 的原因很明确：多步骤（收集信息、分类、格式化）、复用频率高（每个工作日都用）、有清晰边界（只管日报生成）。

第一步，定义接口契约。输入参数设计为三项：

{ "raw_notes": {"type": "string", "required": true}, "date": {"type": "string", "required": false, "format": "YYYY-MM-DD"}, "tone": {"type": "string", "enum": ["formal", "casual"], "default": "formal"} }

第二步，设计处理流程。这个 Skill 内部我分三段：先调用一个轻量分类逻辑，把用户零散的记录按“完成/计划/风险/其他”四类归类。这个过程我用 Pydantic 定义输出结构，然后让模型把输入映射到 JSON。接下来写一个纯代码函数，将归类后的结果按照日报模板排版，处理日期格式、空值兜底。最后用模型润色措辞，将口语化内容转为书面表述，但要求不得改写事实信息。

第三步，实现代码。注意我这里刻意把流程拆成独立函数，方便测试和替换。

第四步，测试。我准备了三组测试数据：一组信息完整的笔记，一组只写了一半信息有缺失的笔记，一组包含敏感词和无关闲聊的笔记。信息完整的要能输出规范日报；信息缺失时要能智能补全日期但是对空白项给占位符而不是瞎编；无关内容要能自动剔除。这个测试用例的设计思路很重要——不要只测理想情况，要专门设计边缘情况。

第五步，注册和联调。配置好名称和描述后接入 Agent 侧做端到端联调。联调时我习惯故意说一些模棱两可的需求，比如“帮我搞个今天的小结”，看 Agent 能不能正确推理出需要调用日报生成 Skill。如果触发失败，第一反应不是调代码，而是看描述写得够不够清楚。

4. 常见问题与排查技巧实录

4.1 问题速查表：调度、执行、结果三类异常

整理一下我实际项目中遇到的典型问题，按表现分类归档。

4.2 排查思路与日志追踪的落地方法

排查 Skill 问题，最忌讳的是直接去看最终答案对不对，你没法判断是哪个环节出了问题。我的习惯是给 Skill 链路设计全链路日志。

每个 Skill 启动时打一行入参摘要日志，结束时打一行输出摘要日志，中间遇到异常打一行错误日志。这一行的格式是固定的，方便检索。摘要不是全量数据，而是关键字段的抽样。比如日报生成 Skill，入参摘要就打“笔记长度/是否含日期/提及任务数”，出参摘要打“分类结果分布/字数/耗时”。有了这三行日志，定位问题的效率立刻上十倍。

如果是模型调用环节的问题，建议开一个“回放模式”，把这个 Skill 的每一步中间结果打印在调试面板里：模型输入了什么、模型输出了什么、触发了哪个分支。回放模式下不用真实用户请求，而是用一个固定的测试数据集，方便做前后版本对比。

4.3 成本失控和性能瓶颈的优化实践

Agent Skill 最大的隐性成本来源于重复调用模型。我遇到过一个大任务，一个 Skill 里面嵌套了十几轮模型对话，最后算下来一次完整执行要花几十万 Token，费用直接把客户吓到了。

优化手段有三个方向。第一，减少模型调用次数。把“调用模型判断分支”这种操作改成硬编码规则，如果条件能用正则、能用哈希匹配，就不要让模型决策。第二，压缩模型输入。每个 Skill 只传需要的上下文，不传历史全量。我在公司内部强制要求每个 Skill 的开发者在代码里写 clear_context 环节，把传入模型的字段缩减到最小集。第三，用便宜模型替换昂贵模型。不是所有环节都需要顶级模型的能力。分类、抽取、格式化这些任务，用轻量模型完全可以胜任。把重模型留给最终的内容生成，整体成本能下降 50% 以上。

性能方面，最常见的瓶颈在串行执行太多。一个任务拆成多个 Skill 时，如果 Skill 之间没有依赖关系，一定要并行走。我见过一个项目，五个 Skill 本来可以并行，结果代码里写成了一个接一个的 await，响应时间直接翻了五倍。优化后从 8 秒降到 2 秒，用户体感完全不同。

4.4 版本管理与兼容性控制经验

Skill 的迭代速度通常很快，一个活跃项目一个月改十几版很正常。但 Agent 侧往往同时依赖好多个 Skill，如果版本之间接口不一致，整个系统就乱了。

我的做法是：所有 Skill 接口必须带版本号，第一阶段用 URL 路径版本管理，比如 /v1/skills/daily-report。Skill 内部实现改了，只要接口契约不变，小版本升级即可；接口破坏性变化，必须升级大版本，并且旧版本保持一段时间兼容运行。

Skill 描述文件的更新也要走版本管理。注册中心里每个 Skill 存一个 version 字段，Agent 启动时做版本比对，发现本地缓存版本旧了就拉取新的技能清单。升级说明文档里要写清楚变了什么、升级注意什么。有一次我没写升级说明直接改了描述，结果 Agent 的调用触发方式全变了，线上出现了一堆错误调用，花了一个晚上才排查清楚问题。从此之后我再也没跳过版本说明这一步。

5. 架构落地后的维护与演进

5.1 技能质量的度量指标怎么定

当一个项目的 Skill 数量多到一定程度后，光靠直觉判断哪个技能好用、哪个技能该淘汰是不现实的，得用指标来管。

我建议监控四个核心指标。第一是调用率，统计某个 Skill 在总请求中的使用占比。调用率极低的 Skill 要么是描述写模糊了、要么是功能真的没用。碰上这种情况，先优化描述看调用率有没有提升，如果连续两周还是低，可以考虑下线。第二是成功率，成功次数除以调用总数，低于 90% 的要重点排查。第三是单次消耗成本，统计每个 Skill 每调用一次的平均 Token 消耗，用来发现成本黑洞。第四是轮均修正次数，用户对 Skill 输出的结果提出进一步修改请求的平均次数——这个指标最能真实反映 Skill 输出质量，因为它直接衡量了用户对结果的不满意度。

这些指标要在仪表盘上实时展示。我习惯在开发和运营阶段同时看，开发阶段关注调用逻辑对不对，运营阶段重点盯成本和用户修正率。

5.2 Skill 的扩展和继承：业务场景的进阶玩法

Skill 做多了以后你会发现，很多 Skill 的核心逻辑是共通的。比如“提取关键信息”这件事，简历解析用到了、合同解析用到了、需求文档解析也用到了。如果每个 Skill 都从零开始写，就重复造轮子了。

我的做法是把共性能力沉淀成基础 Skill，供上层业务 Skill 调用。做一个“文档结构化解析”基础 Skill 之后，简历筛选、合同审核、报告生成这些业务 Skill 都去复用它。改动一处基础逻辑，所有上层 Skill 同步受益。这里要注意基础 Skill 的接口变更影响面会很大，改动前要做充分的兼容性测试。

跨场景组合这块，我举一个实际做过的例子。我们做了一个“数据分析” Skill 和一个“报告生成” Skill，单独用效果已经不错，但组合起来才是真正发挥了 Agent 的潜力——数据分析 Skill 产出统计结果结构体，报告生成 Skill 把这个结构体转化为图文并茂的可视化报告。整个链路完全不需要人工干预，这就是组合的价值。做这个组合时要特别在意两个 Skill 的数据交换格式，格式定义得不一致，到了运行时会疯狂出错。

5.3 从单个 Skill 到 Skill 生态的演进路径

最后聊一下长期演进的方向。单个 Skill 只是开始，真正能让 Agent 战斗力质变的是 Skill 生态。

第一阶段，你有几个孤立 Skill 各自为战，Agent 通过调度层选择使用哪个。第二阶段，Skill 之间开始组合协作，出现复杂的调用链和数据流。第三阶段，Skill 生态形成——基础 Skill、业务 Skill、组合 Skill 分层管理，新业务可以像搭积木一样复用和编排，大量业务需求可以在配置层完成而不用写新代码。

走到第三阶段的企业，Agent 的能力边界已经不再受单个接口的局限，而是面向业务场景无限延展。这个阶段需要关注的就是标准化和治理能力：所有 Skill 都有统一的监控、统一的权限管理、统一的质量标准。这也是我目前的工作重点，在企业里搭一套技能治理机制，让任何团队成员都能安全的创建、测试、发布和下线 Skill，而不是所有人都往一个生产环境里乱丢代码。

我个人在实际操作中的体会是：Agent Skill 的难点从来不在编码本身，而在边界划分、契约设计和质量管控。能把这三个问题想清楚，剩下的就是按部就班的开发工作。如果你正打算在项目里引入 Skill 机制，我的建议是小步快跑——先挑一个最具复用价值的场景做第一个 Skill，跑通全流程后再横向铺开。这套打法比一上来就想搭一套庞大技能体系要靠谱得多。