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 Skill3.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 问题速查表调度、执行、结果三类异常整理一下我实际项目中遇到的典型问题按表现分类归档。现象可能原因优先排查方向Agent 始终不调用你的 Skill描述不清晰、注册信息未同步、参数 schema 有误检查技能注册表是否正常加载然后用一个简单 Prompt 单独测试技能匹配Skill 被调用但传参混乱输入参数描述模糊模型无法正确映射给每个参数追加“业务含义解释”补充触发示例输出格式不稳定结构化约束不够或 temperature 过高输出要求写进系统提示词将 temperature 调低到 0.2 以下逻辑频繁走错误分支分支判断条件覆盖不全缺兜底路径给每个分支写 else 兜底逻辑记录分支命中的日志外部服务超时导致整体失败缺少超时控制和重试加明确的 timeout 参数和指数退避重试策略结果汇总阶段内容丢失上下文太长被截断或拼接逻辑有误拆小处理批次分批汇总后合并日志定位丢弃点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跑通全流程后再横向铺开。这套打法比一上来就想搭一套庞大技能体系要靠谱得多。 
长河君 · 2026/11/3 7:47:02 · 阅读 1.2k Agent Skill 是什么：概念、架构设计与开发实战指南
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 Skill3.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 问题速查表调度、执行、结果三类异常整理一下我实际项目中遇到的典型问题按表现分类归档。现象可能原因优先排查方向Agent 始终不调用你的 Skill描述不清晰、注册信息未同步、参数 schema 有误检查技能注册表是否正常加载然后用一个简单 Prompt 单独测试技能匹配Skill 被调用但传参混乱输入参数描述模糊模型无法正确映射给每个参数追加“业务含义解释”补充触发示例输出格式不稳定结构化约束不够或 temperature 过高输出要求写进系统提示词将 temperature 调低到 0.2 以下逻辑频繁走错误分支分支判断条件覆盖不全缺兜底路径给每个分支写 else 兜底逻辑记录分支命中的日志外部服务超时导致整体失败缺少超时控制和重试加明确的 timeout 参数和指数退避重试策略结果汇总阶段内容丢失上下文太长被截断或拼接逻辑有误拆小处理批次分批汇总后合并日志定位丢弃点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跑通全流程后再横向铺开。这套打法比一上来就想搭一套庞大技能体系要靠谱得多。