1. 从skills这个词说起为什么它突然成了AI Agent圈子的高频词如果你最近在关注AI Agent相关的技术动态大概率会反复看到一个词——skills。它出现在Google Cloud的官方博客里出现在Genkit的文档示例中也出现在各种关于Agent能力扩展的讨论帖里。我第一次注意到这个词是在翻GKE上部署AI agents的案例时发现好几个项目的目录结构里都有一个叫skills的文件夹当时还以为是某种内部命名习惯后来才意识到这已经成了一个约定俗成的概念。简单来说Agent Skills就是给AI Agent装上的技能包。一个裸的Agent哪怕底层模型再强它能做的事情也是有限的——无非是对话、推理、生成文本。但当你给它挂上一个个skill之后它就能查数据库、调API、操作文件、执行代码、走特定的业务流程。这有点像给一个刚入职的聪明新人配工具箱人聪明是基础但真正干活还得靠锤子、扳手、螺丝刀各就各位。这个内容适合谁来参考三类人最值得往下看一是正在用Genkit、LangChain这类框架搭Agent的开发者你大概率已经在写tool了但可能还没把skill这个概念抽象清楚二是在Google Cloud上跑AI agents的工程团队尤其是用GKE做编排的skill的组织方式直接影响你的部署结构三是产品侧的同学理解skill的边界在哪里才能想清楚一个Agent产品到底能承诺什么、不能承诺什么。我写这篇东西的出发点很简单网上关于什么是Agent Skill的科普已经不少了但真正把skill的设计原则、目录结构、注册机制、调试方法、以及踩坑经验讲透的内容不多。我把自己在几个项目里折腾skill的经验整理出来尽量做到你看完就能照着搭一套自己的skill体系。2. Agent Skills的本质它到底解决了什么问题2.1 从一个大prompt到一组可组合的能力单元早期做Agent很多人的做法是把所有能力塞进一个巨大的system prompt里告诉模型你可以做A、可以做B、可以做C然后靠模型自己判断该用哪个。这种做法在能力少的时候能跑一旦超过五六个能力就开始崩——模型会混淆、会漏掉、会在不该用的时候乱用。Skill的思路是把每个能力独立成一个自包含的单元。每个skill有自己的名字、描述、输入输出定义、执行逻辑。Agent在运行时根据当前任务去挑选合适的skill而不是在一堆文字描述里猜。这个转变的意义在于能力从prompt里的描述变成了代码里的实体可测试、可复用、可版本管理。我打个比方。前者像是给员工一本厚厚的员工手册让他自己翻后者像是给员工一个工具墙每个工具挂在自己的位置上用哪个取哪个。工具墙的好处是显而易见的——你能一眼看出有哪些工具、哪个工具缺了、哪个工具该换了。2.2 Skill与Tool的区别别把两个概念混着用这里必须澄清一个常见的混淆。很多人把skill和tool当同义词用其实在大多数框架里它们是有层次差异的。Tool通常指一个具体的函数调用比如get_weather(city)、search_database(query)。它是原子操作输入输出明确做的事情单一。Skill则更像是一个面向任务的能力封装它可能内部调用多个tool可能包含一段特定的推理逻辑可能有自己的状态管理。比如一个客户投诉处理skill内部可能先调query_order、再调check_refund_policy、最后调send_email对外只暴露一个处理投诉的入口。用一句话概括tool是零件skill是模块。零件可以很多很碎模块要有清晰的职责边界。理解这个区别你在设计skill的时候就不会把它写成一个大杂烩也不会把一个完整业务流程拆得七零八落。2.3 为什么Google Cloud和Genkit都在推这个概念Google Cloud在AI agents的文档里反复强调skillGenkit更是把skill作为一等公民来设计背后有很实际的工程考量。第一可观测性。当Agent的行为出问题时如果所有能力都混在一起你很难定位是哪一步错了。Skill作为独立单元每一步的输入输出都能单独记录、单独回放。第二可组合性。同一个skill可以被多个Agent复用。你写了一个查询库存skill客服Agent能用供应链Agent也能用不用重复实现。第三权限与安全。不同skill可以有不同的权限级别。读数据的skill和写数据的skill分开敏感操作可以单独加审批流程。这在企业场景里是刚需。第四迭代效率。改一个skill不影响其他skill测试也只需要测这一个。相比改一大坨prompt然后祈祷别的地方别崩这种隔离性带来的开发体验提升是巨大的。3. 一个Skill的标准结构长什么样3.1 目录组织从文件层面理解skill在Genkit和多数现代Agent框架里一个skill通常对应一个目录。我见过的最清晰的组织方式是这样的skills/ query-inventory/ skill.yaml # 元数据名称、描述、输入输出schema handler.ts # 执行逻辑 prompt.md # 该skill专属的提示词片段 tests/ basic.test.ts # 单元测试 process-refund/ skill.yaml handler.ts prompt.md tests/这个结构不是随便定的。skill.yaml负责声明我是谁、我能接受什么、我会返回什么让框架和Agent能在不加载执行逻辑的情况下就知道这个skill的存在。handler.ts是真正的干活代码。prompt.md放这个skill特有的提示词——注意是skill特有的不是全局的。tests/保证你改代码的时候不会悄悄改坏行为。提示如果你的框架不支持目录式skill至少也要在代码层面把元数据、执行逻辑、提示词三者分开。混在一个文件里三个月后你自己都不想看。3.2 元数据设计描述写得好Agent才选得对skill.yaml里最关键的是description字段。这个描述不是给人看的文档是给Agent用来做选择的依据。写得含糊Agent就会在错误的场景调用它写得精准Agent的选型准确率会明显提升。我踩过的坑早期写描述喜欢用处理用户相关请求这种大而全的表述结果Agent动不动就调这个skill因为它看起来什么都能干。后来改成根据订单号查询当前库存数量仅用于只读查询不修改任何数据误调用率立刻降下来了。好的描述应该包含三个要素做什么、什么场景用、什么场景不用。特别是不用的部分很多人会忽略但它对减少误调用非常有效。3.3 输入输出Schema类型约束是Agent的护栏用Zod、JSON Schema或者框架自带的schema工具定义输入输出看起来是额外工作量实际是在给Agent装护栏。模型生成参数的时候有schema约束和没schema约束出错率差一个数量级。举个具体的例子。一个查询订单的skill输入schema定义成const QueryOrderInput z.object({ orderId: z.string().regex(/^ORD-\d{8}$/), includeItems: z.boolean().default(false), });这个regex约束看起来严格但它能挡掉大量模型瞎编的订单号格式。default则让模型在不确定的时候可以省略参数由代码兜底。实测下来加了这类约束之后因为参数格式错误导致的失败能减少七成以上。输出schema同样重要。它让调用方可能是另一个skill也可能是最终用户界面知道该期待什么结构不用做防御性解析。4. Skill的注册与调度Agent怎么知道有哪些skill可用4.1 注册机制显式注册优于自动扫描框架通常提供两种注册方式显式注册和目录自动扫描。我建议生产环境用显式注册开发环境可以用自动扫描图方便。显式注册的好处是可控。你能清楚知道当前Agent挂了哪些skill不会因为某个目录里多了个文件就悄悄多出一个能力。在GKE上部署的时候显式注册也让构建产物更可预测——你知道打包进去的到底是哪些skill。自动扫描的问题在于隐式依赖。某天有人往skills目录扔了个实验性的skill忘了加测试结果上线后Agent开始调用它出了问题排查半天。这种事我见过不止一次。4.2 调度策略让Agent选还是让代码选Skill的调度有两种模式。一种是Agent自主选择——把所有skill的描述给模型让它根据当前对话决定调哪个。另一种是代码编排——在代码里写死先调A再调B根据A的结果决定调C还是D。我的经验是开放式任务用自主选择流程化任务用代码编排。客服对话这种场景用户下一句说什么完全不可预测适合让Agent自主选skill。而像订单退款这种有明确步骤的流程用代码编排更稳因为步骤之间的依赖关系模型不一定能可靠推理出来。实际项目里往往是混合的外层用代码编排保证主流程每个步骤内部如果需要灵活处理再让Agent在有限的几个skill里自主选。这样既有确定性又有灵活性。4.3 上下文管理skill之间怎么传递信息多个skill协作的时候上下文怎么传是个容易出问题的地方。常见做法是维护一个共享的context对象每个skill可以读、可以写。这里有个坑context膨胀。如果每个skill都往context里塞东西很快context就会大到影响模型性能而且里面很多是无关信息。我的做法是给context分层——全局层放会话级信息用户ID、会话ID任务层放当前任务相关的信息skill执行完就把任务层清掉。这样context始终保持在合理大小。另一个坑是命名冲突。两个skill都往context里写result字段后写的覆盖先写的。解决办法是给每个skill的写入加命名空间比如refund.result、inventory.result避免撞车。5. 实操从零搭一个可用的skill体系5.1 环境准备与依赖安装假设你用Genkit加TypeScript来搭基础环境需要Node.js 20以上、npm或pnpm。初始化项目之后安装核心依赖npm install genkit genkit-ai/googleai zod npm install -D typescript tsx vitest如果你要部署到GKE还需要准备容器化相关的工具链这部分后面单独说。本地开发阶段先把skill跑通再说部署。5.2 写第一个skill查询库存我习惯从最简单的只读skill开始因为它没有副作用调试起来心理负担小。先建目录结构mkdir -p skills/query-inventory/tests然后写skill.yamlname: query-inventory description: 根据商品SKU查询当前可用库存数量。 适用场景用户询问某商品是否有货、还剩多少。 不适用场景修改库存、查询历史库存变动。 input: sku: string, 商品SKU编码格式为SKU-开头加6位数字 output: available: number, 当前可用数量 warehouse: string, 所在仓库编码接着写handler.tsimport { z } from zod; const InputSchema z.object({ sku: z.string().regex(/^SKU-\d{6}$/), }); export const queryInventory { name: query-inventory, inputSchema: InputSchema, handler: async (input: z.infertypeof InputSchema) { // 实际项目里这里查数据库或调内部API const result await inventoryService.query(input.sku); return { available: result.available, warehouse: result.warehouse, }; }, };注意handler里我用了inventoryService这个抽象而不是直接写数据库查询。这样做的好处是测试的时候可以mock掉这个service不用连真实数据库。5.3 注册到Agent并跑通第一次调用注册代码通常长这样import { genkit } from genkit; import { queryInventory } from ./skills/query-inventory/handler; const ai genkit({ plugins: [...] }); ai.defineTool(queryInventory, async (input) { return queryInventory.handler(input); });跑通之后用一句测试输入验证SKU-123456还有货吗观察Agent是否正确调用了这个skill、参数是否传对、返回结果是否被正确理解。注意第一次跑通不代表稳定。我建议至少准备20条不同表述的测试输入覆盖各种说法有没有货、库存多少、还剩几个看Agent的调用准确率。低于90%就说明描述还需要打磨。5.4 参数计算与选择超时和重试怎么定Skill调用外部服务的时候超时和重试策略需要根据实际场景定。我的经验值场景超时重试次数退避策略内部数据库查询2s1固定100ms内部API调用5s2指数退避外部第三方API10s1固定500ms写操作5s0不重试写操作不重试是铁律。读操作重试最多带来延迟写操作重试可能造成重复扣款、重复下单这种严重后果。如果确实需要保证写操作的可靠性用幂等键而不是靠重试。6. 调试与排查skill出问题的时候怎么找6.1 常见问题速查表现象可能原因排查方向Agent不调用skill描述不清晰或场景不匹配检查description是否覆盖了当前表述Agent调用了错误的skill多个skill描述重叠检查是否有职责边界模糊的skill参数格式错误schema约束不足加强regex、enum等约束调用超时外部服务慢或超时设置过短看日志确认耗时分布结果被误解输出结构不清晰检查输出schema和字段命名上下文丢失context传递断链检查skill之间context的读写6.2 日志与追踪把每次skill调用记清楚Skill的可观测性靠日志。我建议每次调用至少记录skill名称、输入参数、输出结果、耗时、是否成功、失败原因。这些信息在排查问题的时候是救命的。更进一步如果框架支持trace把一次对话里所有skill调用串成一条trace能看到完整的调用链。Genkit在这方面做得不错配合Google Cloud的日志服务在GKE上跑的时候可以直接在控制台看到每次调用的详情。6.3 我踩过的三个坑坑一skill描述里用了太多同义词。我写过一个skill描述里同时出现查询、检索、获取三个词本意是覆盖更多表述结果Agent反而困惑了调用准确率下降。后来统一用一个词准确率回升。描述要精准不要贪多。坑二skill内部逻辑太复杂。有个skill我塞了五六个分支处理各种边界情况。结果测试覆盖不全上线后某个分支出错排查了半天。后来拆成三个skill每个职责单一问题立刻清晰了。一个skill只做一件事这句话说起来简单做起来容易忘。坑三忽略了skill的版本管理。改了一个skill的行为没通知依赖它的其他Agent结果另一个Agent的行为悄悄变了。后来我们给skill加了版本号破坏性变更必须升大版本依赖方显式指定版本。这个机制救过我们好几次。7. 部署到GKEskill体系在生产环境的样子7.1 容器化把skill和Agent一起打包Skill的代码和Agent的代码通常打包在同一个容器里因为它们运行时是紧耦合的。Dockerfile大致长这样FROM node:20-slim WORKDIR /app COPY package*.json ./ RUN npm ci --production COPY dist/ ./dist/ COPY skills/ ./skills/ CMD [node, dist/main.js]注意skills/目录要显式COPY进去别指望构建产物自动包含。我见过有人忘了这步本地跑得好好的部署上去Agent一个skill都找不到。7.2 配置管理skill的开关和参数生产环境里skill的启用与否、超时参数、外部服务地址这些应该走配置不要硬编码。用环境变量或者配置中心都行关键是改配置不用重新构建镜像。我们现在的做法是每个skill的配置放在一个统一的config里启动时加载。这样紧急情况下可以快速禁用某个出问题的skill不用走完整的发布流程。7.3 灰度与回滚新skill上线怎么控风险新skill上线我建议先灰度。让一小部分流量走新版本观察一段时间再全量。GKE的滚动更新配合流量切分能做这件事。回滚要提前准备好。Skill出问题的时候最快的恢复方式是回滚到上一个版本而不是现场修bug。所以每次发布都要保证上一个版本的镜像还在回滚命令要提前演练过。8. 关于skill设计我个人的几条经验写到这里把散落在各处的经验收拢一下都是实际项目里验证过的。skill的粒度宁小勿大。一个skill如果超过200行代码大概率该拆了。小粒度带来的组合灵活性远大于大粒度带来的省事。描述是skill的灵魂。花在打磨description上的时间回报率比花在优化handler逻辑上还高。因为Agent选错skill逻辑写得再好也没用。测试要覆盖不该调用的场景。大多数人只测该调用的时候调没调忽略了不该调用的时候有没有乱调。后者往往才是生产事故的来源。skill之间尽量不共享状态。共享状态带来的耦合会在你改一个skill的时候以意想不到的方式影响另一个。如果非要共享通过明确的context接口而不是全局变量。版本管理从第一天就要有。哪怕现在只有一个Agent用你的skill也把版本号加上。等到有第二个依赖方的时候你会感谢自己当初的决定。这套东西我用了大半年从最初一个项目里三四个skill到现在跨多个项目复用几十个skill整体上是越用越顺的。核心就一句话把skill当成有明确契约的独立模块来对待而不是prompt的附属品。这个心态转变过来之后很多设计决策就自然清晰了。