1. 从“skills”这个标题说起它到底指什么第一次看到“skills”这个标题很多人会以为是泛泛而谈的能力清单或者某个招聘网站上的技能标签页。但结合热搜词里反复出现的 Agent Skills、Google Cloud、GKE、Genkit、codex skills、claude agent skills 这些词方向其实很明确——这里说的 skills是围绕 AI Agent智能体构建的一套可插拔能力模块体系。简单讲就是给一个通用的大模型智能体装上一个个“技能包”让它从只会聊天变成能查数据库、能调接口、能跑部署、能写论文、能做分镜脚本的干活工具。我最早接触这个概念是在做自动化运维助手的时候。当时团队想让一个 Agent 既能查 GKE 集群状态又能根据告警自动生成排查报告还要能调用 Genkit 写好的流式处理逻辑。如果每个功能都硬编码进主流程代码会膨胀到没法维护。后来把每个能力拆成独立的 skill主 Agent 只负责路由和编排整个系统才清爽起来。这也是为什么 skills 这个词会跟 Google Cloud、GKE、Genkit 绑在一起——它们代表的是云端基础设施、容器编排和 AI 应用框架这三层而 skills 就是贯穿这三层的“能力接口层”。这篇文章适合谁看如果你是刚听说 Agent Skills 想搞明白它和普通函数调用有什么区别的开发者或者你已经在用 codex、claude 这类工具但不知道怎么把自定义能力接进去再或者你负责一个 GKE 上的 AI 应用、想用 Genkit 做编排但卡在技能注册这一步那下面的内容应该能帮你省掉不少翻文档和试错的时间。我会从设计思路讲到实操细节再到踩过的坑尽量把“为什么这么设计”和“具体怎么落地”都说清楚。2. Agent Skills 的整体设计与核心思路拆解2.1 为什么不是简单的函数调用而要搞一套 skills 体系很多人第一反应是我直接写个函数让 Agent 去调不就行了早期我也是这么干的。但很快问题就来了。第一函数签名和描述是给程序员看的大模型看不懂参数含义它需要的是自然语言描述的能力边界和输入输出说明。第二函数调用没有版本管理和权限隔离一个 Agent 能调所有函数出了事没法追溯。第三不同来源的能力比如 Google Cloud 官方提供的、社区贡献的、你自己写的混在一起没有统一的发现和加载机制。Skills 体系本质上解决的是三个问题能力描述标准化、加载与发现机制、执行隔离与可观测性。一个 skill 通常包含几部分一个描述文件告诉 Agent 这个技能是干什么的、什么时候用、输入输出是什么、一个执行入口可以是云函数、容器、或者本地脚本、以及可选的权限声明和依赖清单。Agent 在规划任务时先根据描述文件做语义匹配选中 skill 后再按声明的协议去调用执行入口。这种设计的好处在于Agent 的“大脑”和“手脚”解耦了。大脑可以换模型、换编排框架手脚可以独立升级、独立测试。我在 GKE 上部署过一个客服 Agent把查订单、改地址、发优惠券三个能力做成独立 skill后来业务方要改优惠券逻辑只更新那个 skill 的镜像就行完全不用动主 Agent 的代码。这就是解耦带来的实际收益。2.2 和 Google Cloud、GKE、Genkit 的关系到底是什么热搜词里这几个词不是随便凑的。Google Cloud 提供的是底层资源Cloud Run 用来跑无状态的 skill 执行入口Cloud Storage 存 skill 包Secret Manager 管密钥。GKE 则是当你的 skill 数量多、需要长驻服务或者有状态处理时用的容器编排层。Genkit 是 Google 出的 AI 应用开发框架它原生支持定义 tool工具和 flow流程而 tool 在概念上就是 skill 的一种实现形式。我自己的习惯是轻量级、事件驱动的 skill 直接扔 Cloud Run按调用付费冷启动可以接受需要保持长连接或者跑批处理的 skill 放 GKE用 Deployment 管理副本而 Genkit 主要用来做本地开发和流程编排测试它的 dev UI 能很直观地看到 Agent 选了哪个 tool、传了什么参数、返回了什么结果调试阶段特别省事。注意不要把 Genkit 的 tool 和 skill 完全等同。Genkit tool 更偏向于在单个应用内定义的可调用函数而 skill 更强调跨应用、跨团队的可复用能力包。你可以把 Genkit tool 打包成 skill但反过来不一定成立。2.3 一个 skill 的生命周期从注册到执行到下线理解 skills 体系最好把它当成一个有生命周期的对象来看。我把它分成五个阶段定义、注册、发现、执行、退役。定义阶段要写清楚 skill 的元数据包括名称、版本、描述、输入 schema、输出 schema、所需权限、依赖项。注册阶段是把 skill 包上传到仓库或者注册中心让 Agent 能查到。发现阶段是 Agent 在规划时根据当前任务语义去匹配可用 skill。执行阶段是实际调用这里要考虑超时、重试、错误处理。退役阶段是当 skill 不再需要时从注册中心摘除但保留历史版本以便回滚。很多团队只做了定义和执行忽略了注册和发现结果就是 skill 散落在各个代码库里Agent 根本不知道有哪些能力可用。我见过一个项目三个团队各自写了十几个 skill但没有统一注册最后主 Agent 只能硬编码调用路径完全失去了 skills 体系的灵活性。所以从第一天起就要把注册中心建起来哪怕只是一个简单的 JSON 索引文件放在对象存储里。3. 核心细节解析与实操要点3.1 skill 描述文件怎么写才能让 Agent 选得准描述文件是 Agent 选择 skill 的唯一依据写得好不好直接决定调用准确率。我踩过的最大坑是描述写得太技术化比如“调用 GKE API 获取 Pod 列表”Agent 在面对“帮我看看集群里有哪些服务在跑”这种自然语言时匹配度很低。后来改成“查询 Kubernetes 集群中正在运行的容器组信息适用于排查服务状态和资源占用”命中率明显提升。描述文件一般用 YAML 或 JSON核心字段包括name唯一标识用短横线分隔比如gke-list-podsversion语义化版本方便灰度发布description自然语言描述要包含使用场景和触发条件input_schemaJSON Schema 格式定义参数类型和必填项output_schema同样用 JSON Schema让 Agent 知道返回结构permissions声明需要哪些权限比如读集群、写数据库endpoint执行入口地址可以是 HTTP URL 或消息队列主题实操心得description 里一定要写“什么时候用”和“什么时候不用”。比如“当用户询问集群节点状态时使用不适用于查询应用日志日志查询请使用 log-search skill”。这样能大幅减少 Agent 误选。3.2 输入输出 schema 的设计陷阱JSON Schema 看起来简单但有几个细节容易翻车。第一不要用过于复杂的嵌套结构。Agent 在生成参数时嵌套层级越深出错概率越高。我一般控制在两层以内超过两层就拆成多个 skill。第二枚举值要写全并且给每个枚举值加描述。比如status字段有running、pending、failed要分别说明含义否则 Agent 可能传一个不存在的值。第三必填项要克制。除了真正必需的参数其他都设成可选并给默认值降低 Agent 的生成负担。还有一个容易被忽略的点输出 schema 要尽量扁平化。如果 skill 返回一个很深的 JSON 树Agent 在后续推理时容易丢失上下文。我的做法是在 skill 内部做一次转换把关键字段提取到顶层原始数据放在raw字段里备查。这样 Agent 读起来轻松需要细节时也能拿到。3.3 权限隔离与密钥管理Skills 体系里最危险的就是权限过大。一个查日志的 skill 如果拿到了写数据库的密钥一旦被恶意提示词利用后果很严重。我的原则是最小权限 运行时注入。每个 skill 在描述文件里声明自己需要的权限注册中心在加载时校验执行入口在启动时从 Secret Manager 拉取对应密钥而不是把密钥写在环境变量或代码里。在 GKE 上可以用 Workload Identity 把 Kubernetes Service Account 和 Google Cloud Service Account 绑定skill 容器直接用云 SDK 时自动获得临时凭证完全不用管密钥文件。Cloud Run 也有类似的机制通过服务账号绑定实现。这样即使 skill 镜像被泄露攻击者也拿不到长期有效的密钥。注意不要给 skill 授予owner或editor这类粗粒度角色。GKE 相关操作尽量用自定义角色只开放需要的 API 权限。我见过一个 skill 因为用了默认计算服务账号结果能操作整个项目的资源这是非常危险的。3.4 超时、重试与幂等性设计Agent 调用 skill 时网络抖动、服务重启、下游限流都是常态。如果不做超时和重试Agent 会卡住或者得到不一致的结果。我的经验值是查询类 skill 超时设 10 秒写入类设 30 秒批处理类单独走异步任务。重试策略用指数退避最多三次并且只对幂等操作重试。幂等性怎么保证对于写操作让调用方传一个request_idskill 内部用这个 ID 做去重。如果同一个request_id重复到达直接返回上次的结果。这个request_id可以由 Agent 在规划时生成也可以由编排层统一分配。我在 Genkit 里做流程编排时会在 flow 入口生成 UUID 并透传给所有 skill这样即使某个 skill 被重试也不会产生重复副作用。4. 实操过程与核心环节实现4.1 环境准备本地开发与云端部署的衔接本地开发阶段我推荐用 Genkit 的 CLI 工具初始化项目。它会生成一个标准的目录结构包含tools文件夹用来放 skill 定义flows文件夹用来放编排逻辑。安装命令很简单npm install -g genkit-cli genkit init my-agent-project初始化完成后在tools目录下新建一个 skill 文件比如gke-list-pods.ts。Genkit 的 tool 定义方式很直观import { tool } from genkit-ai/core; import { z } from zod; export const gkeListPods tool( { name: gke-list-pods, description: 查询 GKE 集群中指定命名空间下的 Pod 列表适用于排查服务运行状态, inputSchema: z.object({ clusterName: z.string().describe(GKE 集群名称), namespace: z.string().default(default).describe(命名空间默认为 default), statusFilter: z.enum([all, running, pending, failed]).default(all) }), outputSchema: z.object({ pods: z.array(z.object({ name: z.string(), status: z.string(), restarts: z.number(), age: z.string() })), total: z.number() }) }, async (input) { // 实际调用 GKE API 的逻辑 const pods await fetchPodsFromGKE(input.clusterName, input.namespace); const filtered input.statusFilter all ? pods : pods.filter(p p.status input.statusFilter); return { pods: filtered.map(p ({ name: p.metadata.name, status: p.status.phase, restarts: p.status.containerStatuses?.[0]?.restartCount ?? 0, age: calculateAge(p.metadata.creationTimestamp) })), total: filtered.length }; } );本地跑genkit start会启动一个开发服务器自带 UI 可以手动测试每个 skill 的输入输出。这个 UI 我强烈建议多用它能看到 Agent 实际生成的参数和 skill 返回的原始数据比看日志快得多。4.2 把 skill 部署到 Cloud Run 并注册到索引本地测试通过后下一步是部署。Cloud Run 部署 skill 有两种方式一种是把每个 skill 单独打成一个容器另一种是把多个相关 skill 打成一个容器通过不同路径区分。我倾向于后者因为冷启动次数少而且相关 skill 往往共享依赖。Dockerfile 大概长这样FROM node:20-slim WORKDIR /app COPY package*.json ./ RUN npm ci --production COPY dist/ ./dist/ ENV PORT8080 CMD [node, dist/server.js]部署命令gcloud run deploy skill-gke-ops \ --source . \ --region us-central1 \ --no-allow-unauthenticated \ --service-account skill-runnermy-project.iam.gserviceaccount.com \ --set-secrets GKE_API_KEYgke-api-key:latest部署完成后把服务地址和 skill 描述写入注册索引。我用的是一个简单的 JSON 文件放在 Cloud Storage 里结构如下{ skills: [ { name: gke-list-pods, version: 1.0.0, endpoint: https://skill-gke-ops-xxx.run.app/gke-list-pods, description: 查询 GKE 集群中指定命名空间下的 Pod 列表, input_schema_ref: gs://my-bucket/schemas/gke-list-pods-input.json, permissions: [gke.read] } ] }Agent 启动时拉取这个索引把每个 skill 的描述和 schema 注入到系统提示词里规划时就能看到所有可用能力。4.3 用 Genkit 做多 skill 编排的完整流程单个 skill 跑通后真正的挑战是编排。比如用户说“帮我检查一下生产集群有没有异常 Pod有的话把日志拉出来”这需要先调gke-list-pods根据结果判断是否有异常再调log-search拉日志。Genkit 的 flow 就是干这个的。import { defineFlow } from genkit-ai/flow; import { gkeListPods } from ./tools/gke-list-pods; import { logSearch } from ./tools/log-search; export const diagnoseClusterFlow defineFlow( { name: diagnose-cluster, inputSchema: z.object({ clusterName: z.string() }), outputSchema: z.object({ summary: z.string(), details: z.array(z.any()) }) }, async (input) { const podResult await gkeListPods({ clusterName: input.clusterName, namespace: production, statusFilter: failed }); if (podResult.total 0) { return { summary: 生产集群无异常 Pod, details: [] }; } const details []; for (const pod of podResult.pods) { const logs await logSearch({ clusterName: input.clusterName, podName: pod.name, lines: 50 }); details.push({ pod: pod.name, logs: logs.entries }); } return { summary: 发现 ${podResult.total} 个异常 Pod已拉取日志, details }; } );这个 flow 里skill 的调用是显式的但实际生产环境中我更推荐让 Agent 自己规划。做法是把所有 skill 注册给 Agent用 Genkit 的generate配合 tool 调用让模型决定调哪个、传什么参数。两种方式各有适用场景流程固定的用显式编排灵活多变的用 Agent 自主规划。4.4 在 GKE 上部署有状态 skill 的注意事项有些 skill 需要保持状态比如维护一个长连接池、缓存热点数据、或者跑定时任务。这类 skill 不适合 Cloud Run要放 GKE。部署时注意几点第一用 StatefulSet 而不是 Deployment保证 Pod 名称稳定方便 skill 内部做分片。第二配置 PodDisruptionBudget避免滚动更新时所有副本同时挂掉。第三用 HorizontalPodAutoscaler 根据自定义指标比如队列长度扩缩容而不是只看 CPU。我部署过一个日志聚合 skill用 StatefulSet 跑三个副本每个副本负责一部分集群的日志拉取通过一致性哈希分配。这样单个副本挂掉只影响部分数据恢复后自动重新平衡。如果当时用 DeploymentPod 名称随机哈希分配就乱了。实操心得GKE 上的 skill 容器一定要配 readinessProbe 和 livenessProbe。readinessProbe 检查依赖的下游服务是否可达livenessProbe 检查进程是否卡死。我见过一个 skill 因为下游数据库连接池耗尽进程还在但完全没响应没有 livenessProbe 就一直僵着Agent 调用全部超时。5. 常见问题与排查技巧实录5.1 Agent 选错 skill 怎么办这是最高频的问题。表现是用户问 A 场景Agent 调了 B skill。排查思路分三步第一看 skill 描述是否有语义重叠。比如gke-list-pods和gke-list-deployments的描述如果都写了“查询 GKE 资源”Agent 就容易混。解决办法是在描述里明确区分对象一个写“容器组 Pod”一个写“部署 Deployment”。第二看输入 schema 是否有冲突。如果两个 skill 的必填参数很像Agent 可能随机选。可以给其中一个加一个独特的必填参数比如resourceType枚举。第三看系统提示词里 skill 列表的顺序。有些模型对靠前的 skill 有偏好可以把高频 skill 放前面低频放后面。如果以上都调了还是不准可以在编排层加一个路由 skill专门做意图分类把用户请求先分到大类再在大类里选具体 skill。这相当于加了一层粗筛准确率会高很多。5.2 skill 执行超时或返回格式错误超时问题先看 skill 自身的日志确认是下游慢还是 skill 内部逻辑慢。如果是下游 API 慢考虑加缓存或者异步化。如果是 skill 内部慢检查是否有同步阻塞操作比如大文件读写、复杂计算。Genkit 的 trace 功能能看到每个步骤的耗时定位很快。返回格式错误通常是 schema 不匹配。Agent 期望的是 JSONskill 返回了纯文本或者字段名对不上。解决办法是在 skill 出口加一层校验用 JSON Schema 验证输出不符合就抛错并记录原始输出。这样至少能快速发现问题而不是让 Agent 拿到脏数据后产生幻觉。5.3 常见问题速查表问题现象可能原因排查方法解决措施Agent 不调用任何 skill描述文件未加载或格式错误检查注册索引是否可访问schema 是否合法修复索引路径用 JSON 校验工具验证调用参数缺失必填项输入 schema 描述不清查看 Agent 生成的参数和 schema 对比给参数加详细描述和示例值skill 返回 403权限不足或密钥过期查看 skill 日志中的错误码检查服务账号权限轮换密钥重复执行产生副作用缺少幂等设计检查是否有 request_id 去重在 skill 入口加幂等键校验响应时间波动大冷启动或下游限流看 Cloud Run 冷启动指标和下游 QPS设最小实例数加请求队列Agent 选错 skill描述语义重叠对比多个 skill 的描述文本细化描述加区分性关键词5.4 独家避坑技巧版本管理与灰度发布Skills 一旦上线就不能随便改。我吃过亏直接更新了一个 skill 的逻辑结果 Agent 的行为突然变了排查了半天才发现是 skill 版本不一致。后来我强制要求所有 skill 必须带版本号注册索引里同时保留多个版本Agent 默认调最新稳定版但可以通过配置指定版本。灰度发布怎么做新版本 skill 先注册但不加入默认列表用一个小流量 Agent 去调观察一段时间没问题再切主流量。Genkit 的 flow 支持根据条件路由到不同版本的 skill实现起来不难。关键是要有回滚预案一旦新版本出问题能立刻切回旧版本。注意不要删除旧版本 skill 的镜像和注册信息至少保留三个月。我见过团队为了“清理”把旧版本删了结果新版本出问题想回滚都回不去只能紧急修 bug非常被动。6. 从单点 skill 到 skill 生态的扩展思路单个 skill 跑通只是起点真正有价值的是形成可复用的 skill 生态。我在团队内部推动过一个做法每个 skill 除了代码还要配一份“使用说明”包括适用场景、输入输出示例、常见错误码、依赖的下游服务。这份说明不光是给人看的也是给 Agent 看的——把说明的关键部分自动注入到 skill 描述里Agent 的调用准确率会进一步提升。另一个扩展方向是 skill 的组合。有些复杂任务可以拆成多个基础 skill 的组合比如“部署新版本”可以拆成“构建镜像”“更新 Deployment”“等待滚动完成”“验证健康检查”四个 skill。Agent 编排时按顺序调用每个 skill 只做一件事这样复用性最高。我现在的习惯是写 skill 之前先问自己这个能力能不能再拆拆到不能再拆为止。最后分享一个我实际使用中的体会skills 体系的维护成本主要不在写代码而在写描述和管版本。描述写得好Agent 就聪明版本管得严系统就稳定。这两件事看起来琐碎但决定了整个体系能不能长期跑下去。我见过太多项目因为描述随意、版本混乱最后 Agent 行为不可预测只能推倒重来。所以从第一个 skill 开始就把描述和版本当成一等公民对待后面会省心很多。