Agent Skills 工程化实践：从概念到 GKE 与 Genkit 落地

1. 从"skills"这个热词说起：它到底在解决什么问题

最近一段时间，"skills"这个词在技术社区里出现的频率高得离谱。不管是在云原生圈子里聊 GKE 部署，还是在 AI 应用开发群里讨论 Genkit 工作流，甚至在前端开发者聚会上，都有人把"skills"挂在嘴边。但如果你仔细追问一句"你说的 skills 具体指什么"，十个人可能会给你八个不同的答案。有人说是 Agent 的能力单元，有人说是可复用的工具包，还有人把它理解成某种技能市场的商品化封装。

这种概念上的模糊，恰恰说明"skills"正处在一个从野蛮生长走向标准化的临界点上。我接触这个概念最早是在做 Google Cloud 上的智能体项目时，当时团队需要让一个 Agent 既能查数据库、又能调外部 API、还能做文档解析，如果每个能力都硬编码在 Agent 主逻辑里，代码会迅速膨胀到无法维护。后来我们把每个独立能力抽出来，定义成一个个自包含的 skill，Agent 只负责编排和调度，整个架构一下子就清爽了。

所以这篇文章想做的事情很明确：把"skills"这个概念从热词还原成可落地的工程实践。我会围绕 Agent Skills 的核心设计思路、在 Google Cloud 生态（特别是 GKE 和 Genkit）里的集成方式、开发一个 skill 的完整流程、以及实际踩过的坑，做一次系统性的拆解。不管你是刚听说这个词想搞清楚它是什么，还是已经在做 Agent 开发想找一套可复用的方法论，下面这些内容应该都能给你一些参考。

需要提前说明的是，skills 这个概念目前并没有一个放之四海而皆准的官方定义，不同平台、不同框架下的实现差异很大。我下面讲的内容，是基于我在实际项目中总结出来的一套相对通用的理解方式，结合 Google Cloud 生态里常见的工具链来展开。如果你用的是其他技术栈，思路可以借鉴，但具体 API 和配置需要对照你所用平台的文档来调整。

2. Agent Skills 的本质：把"能力"从"编排"里剥出来

2.1 为什么需要 skills 这一层抽象

要理解 skills 的价值，得先看没有它的时候，Agent 开发是什么样子。假设你要做一个客服场景的智能体，它需要：查询订单状态、发起退款、查询物流、回答常见问题。最直接的做法是在 Agent 的主循环里写一堆 if-else 或者 switch-case，根据用户意图路由到不同的处理函数。这种做法在只有三四个功能的时候还能忍，一旦功能扩展到二三十个，主循环就会变成一坨谁都不敢动的意大利面条。

更麻烦的是复用问题。订单查询这个能力，客服 Agent 需要，售后 Agent 也需要，运营分析 Agent 可能还需要。如果每个 Agent 都复制一份实现，那维护成本就是成倍增长。而且不同 Agent 对同一个能力的调用方式可能略有差异，复制之后很容易出现"这个 Agent 的订单查询修了 bug，那个 Agent 的还没修"的情况。

skills 这一层抽象要解决的就是这两个问题：解耦和复用。每个 skill 是一个独立的能力单元，它对外暴露清晰的输入输出接口，内部实现完全封装。Agent 不需要知道这个 skill 内部是怎么查数据库的、怎么调 API 的，只需要知道"我给它一个订单号，它返回订单详情"就够了。这样一来，Agent 的编排逻辑和能力实现就彻底分开了，各自可以独立演进。

2.2 一个 skill 应该包含哪些要素

我在实际项目里总结下来，一个设计良好的 skill 通常包含这么几个部分。首先是元数据描述，包括 skill 的名称、用途说明、适用场景。这部分看起来不起眼，但在 Agent 自动选择 skill 的场景下至关重要——Agent 需要根据用户意图和 skill 描述做匹配，描述写得含糊，匹配就会出错。

其次是输入参数的 schema 定义。这里我强烈建议用 JSON Schema 或者类似的强类型描述方式，把每个参数的类型、是否必填、取值范围、默认值都写清楚。我见过太多项目因为参数定义不严谨，导致 Agent 传了错误类型的参数进来，skill 内部报错，排查半天才发现是 schema 没约束好。

第三是执行逻辑，也就是这个 skill 真正干活的部分。这部分可以是调用一个内部服务、执行一段数据库查询、调用一个外部 API，甚至可以是调用另一个 skill。执行逻辑要处理好异常情况，返回结构化的错误信息，而不是直接抛一个裸异常出去。

最后是输出格式定义。输出同样需要结构化，最好和输入一样有明确的 schema。这样 Agent 拿到结果之后可以稳定地解析，而不是去猜"这个字段到底有没有值"。

2.3 skills 和传统函数/微服务的区别

有人可能会问，这不就是函数封装吗，和我写一个工具类有什么区别？区别在于面向的对象不同。传统函数是给人用的，调用者是人，人可以根据文档理解参数含义、处理返回值。而 skill 是给 Agent 用的，Agent 没有人类的常识和上下文理解能力，它完全依赖 skill 的元数据和 schema 来做决策。

这就带来几个额外的要求。第一，skill 的描述必须足够清晰和自解释，因为 Agent 可能在没有人工干预的情况下自主选择调用哪个 skill。第二，skill 的容错性要更强，因为 Agent 可能会传入一些人类不会传的奇怪参数，skill 需要优雅地处理这些情况而不是直接崩溃。第三，skill 的粒度要合适，太细会导致 Agent 需要组合很多 skill 才能完成一个任务，太粗又会失去复用价值。

和微服务相比，skills 通常更轻量，不一定需要独立的部署单元和网络边界。一个 skill 可以就是一个进程内的模块，也可以是一个独立的服务，取决于你的架构需求。在 Google Cloud 的生态里，我见过把 skill 部署成 Cloud Function 的做法，也见过直接在 Genkit 的 flow 里定义 skill 的做法，两种方式各有适用场景。

3. 在 Google Cloud 生态里落地 skills 的几种路径

3.1 Genkit 里的 skill 定义方式

Genkit 是 Google 推出的 AI 应用开发框架，它本身对"工具调用"有比较完善的支持，而 skill 在概念上和 tool 有很大的重叠。在 Genkit 里定义一个 skill，通常是通过defineTool这个 API 来完成的。你需要提供工具的名称、描述、输入 schema（用 Zod 定义）、以及一个异步的执行函数。

我实际用下来，Genkit 这套机制的好处是类型安全做得很到位。因为输入 schema 是用 Zod 定义的，TypeScript 能在编译期就帮你检查参数类型，执行函数里的参数也是强类型的，不用手动做类型转换和校验。输出同样可以用 Zod 定义，框架会自动帮你做序列化。

但这里有个坑需要注意：Genkit 的 tool 描述会被发送给底层的大模型，用来做工具选择。所以描述文字不能写得太长，否则会占用大量 token；但也不能太短，否则模型理解不了这个工具是干什么的。我的经验是控制在两三句话以内，第一句说清楚"这个工具做什么"，第二句说清楚"什么时候该用它"，必要时第三句补充"它返回什么"。

3.2 GKE 上部署 skill 服务的考量

如果你的 skill 需要独立部署、独立扩缩容，那 GKE 是一个很自然的选择。把每个 skill 或者一组相关的 skill 打包成一个容器，部署成 GKE 上的一个 Deployment，通过 Service 暴露出来，Agent 通过 HTTP 或者 gRPC 调用。

这种做法的优势是隔离性好，一个 skill 出问题不会影响其他 skill，而且可以针对每个 skill 的负载特征单独配置资源。比如查询类的 skill 可能是 IO 密集型，需要更多的并发；而计算类的 skill 可能是 CPU 密集型，需要更强的单核性能。在 GKE 上你可以给不同的 Deployment 配置不同的资源 request 和 limit。

不过这种做法的代价是运维复杂度上升。你需要管理容器镜像、配置 Service 和 Ingress、处理服务发现、做健康检查、配置日志和监控。如果 skill 数量不多，或者调用频率不高，把这些精力花在拆分部署上可能不太划算。我的建议是，先用进程内模块的方式快速迭代，等某个 skill 确实成为瓶颈或者有独立扩缩容需求时，再把它拆出去。

在 GKE 上部署 skill 服务时，有几个配置项值得特别注意。Readiness Probe一定要配，否则流量可能会打到还没初始化完成的 Pod 上。Resource Request不要设得太低，否则 Pod 可能被调度到资源紧张的节点上导致性能抖动。Horizontal Pod Autoscaler的指标选择要结合 skill 的特性，IO 密集型的看 QPS，CPU 密集型的看 CPU 利用率。

3.3 三种集成路径的对比

为了让你更直观地做选择，我把常见的三种 skill 集成方式整理成了一张表：

这张表不是让你二选一，实际项目里往往是混合使用。比如核心的高频 skill 放在进程内，低频的、资源消耗大的 skill 放到 Cloud Function，需要长连接或者有状态处理的 skill 部署到 GKE。关键是根据每个 skill 的实际特征来选择最合适的形态，而不是一刀切。

4. 从零开发一个 skill 的完整流程

4.1 需求拆解：先想清楚边界再动手

开发 skill 最容易犯的错误就是一上来就写代码。我踩过好几次这个坑，写着写着发现这个 skill 承担了太多职责，或者和另一个 skill 的边界模糊不清，最后不得不推倒重来。所以第一步一定是把需求拆解清楚。

拆解的核心问题是：这个 skill 的输入是什么，输出是什么，它不负责什么。最后这一点特别重要。比如一个"订单查询"skill，它负责根据订单号返回订单详情，但它不负责判断这个订单能不能退款，也不负责计算退款金额。那些是"退款"skill 的职责。把边界划清楚，skill 才能保持单一职责，才能被不同场景复用。

我通常会用一张简单的表格来梳理 skill 的边界，列出输入、输出、以及明确排除的职责。这个过程看起来繁琐，但能省下后面大量的返工时间。

4.2 定义输入输出 schema 的实操细节

Schema 定义是 skill 开发里最需要花心思的部分。以订单查询为例，输入可能就是一个订单号字符串，但这里就有讲究了：订单号的格式是什么？有没有校验规则？如果传了不存在的订单号，是返回空还是报错？

我的做法是，输入 schema 尽量严格，把能约束的都约束上。订单号可以用正则约束格式，必填字段明确标记，可选字段给默认值。输出 schema 则要考虑到各种情况，比如订单存在时返回完整信息，订单不存在时返回一个明确的"未找到"状态，而不是抛异常。这样 Agent 拿到结果后可以根据状态字段做不同的处理，而不是去捕获异常。

在 Genkit 里用 Zod 定义 schema 大概是这样：

import { z } from 'genkit'; const OrderQueryInput = z.object({ orderId: z.string().regex(/^ORD\d{10}$/).describe('订单号，格式为 ORD 加 10 位数字'), includeItems: z.boolean().default(true).describe('是否返回订单商品明细'), }); const OrderQueryOutput = z.object({ status: z.enum(['found', 'not_found', 'error']), order: z.object({ id: z.string(), amount: z.number(), createdAt: z.string(), items: z.array(z.object({ name: z.string(), quantity: z.number(), })).optional(), }).optional(), errorMessage: z.string().optional(), });

注意.describe()的用法，这些描述会随 schema 一起传给模型，帮助模型理解每个字段的含义。别小看这几句描述，在模型做参数填充的时候，有没有描述准确率差别很大。

4.3 执行逻辑的异常处理与超时控制

执行逻辑部分，除了正常的业务处理，最重要的是异常处理和超时控制。Agent 调用 skill 的场景下，你无法假设调用方会妥善处理异常，所以 skill 自身必须把各种异常情况都考虑到，并转换成结构化的输出。

我一般会把异常分成几类：输入异常（参数格式不对、必填字段缺失）、业务异常（订单不存在、权限不足）、系统异常（数据库连接失败、外部 API 超时）。输入异常应该在 schema 校验阶段就拦截掉，业务异常转换成明确的业务状态码返回，系统异常则要记录详细日志并返回一个通用的错误状态。

超时控制同样关键。如果 skill 内部要调用外部服务，一定要设置超时时间，不能让请求无限期挂起。在 GKE 上部署的话，还要注意 Pod 的 terminationGracePeriodSeconds 和 skill 内部超时的配合，避免 Pod 被终止时还有请求在处理。

4.4 本地测试与调试的实用技巧

Skill 开发完之后，本地测试这一步不能省。我的习惯是给每个 skill 写一组测试用例，覆盖正常路径、边界情况、异常情况。正常路径就是标准的输入输出验证，边界情况包括空值、极值、格式边界，异常情况则模拟各种失败场景。

调试的时候有个小技巧：在 skill 的执行逻辑里加上结构化的日志，把输入参数、关键中间状态、输出结果都打出来。这样当 Agent 调用出问题时，你可以通过日志快速定位是参数传错了、还是 skill 内部逻辑有问题。日志的字段名要统一，方便后续做聚合分析。

另外，Genkit 提供了一个开发者 UI，可以让你在浏览器里直接测试 tool 的调用。这个工具在调试阶段非常好用，你可以手动填入参数，看 skill 返回什么，不用每次都跑完整的 Agent 流程。我一般在 skill 开发阶段会一直开着这个 UI，改完代码热重载后直接测试。

5. 那些文档里不会写的踩坑经验

5.1 skill 描述写得太"聪明"反而坏事

我刚开始做 skill 的时候，总想把描述写得尽可能全面，把所有可能的使用场景都列上去。结果发现模型反而更容易选错 skill。后来才明白，模型做工具选择时，描述太长会导致关键信息被稀释，而且多个 skill 的描述如果都很长且相似，模型很难区分。

正确的做法是描述要精准而克制。用一句话说清楚这个 skill 的核心用途，再用一句话说明它和其他相似 skill 的区别。比如"查询订单详情"和"查询物流信息"这两个 skill，描述里就要明确前者返回的是订单金额、商品等，后者返回的是配送状态、预计到达时间。让模型一眼就能看出该选哪个。

5.2 参数默认值在 Agent 场景下的陷阱

给参数设默认值在普通函数里是很常见的做法，但在 skill 场景下要格外小心。因为 Agent 在填充参数时，如果某个参数没有从用户输入里提取到，它可能会依赖默认值。如果默认值设得不合理，就会导致 skill 用错误的参数执行。

我的经验是，对于业务含义明确的参数，尽量不要设默认值，而是设为必填。让 Agent 在参数缺失时明确地向用户追问，而不是用一个默认值糊弄过去。只有那些确实有合理默认值的参数（比如分页大小默认 20 条），才设置默认值。

5.3 并发调用下的状态污染问题

这个问题在 skill 需要维护内部状态时特别容易出现。比如一个 skill 内部缓存了一些数据，多个 Agent 并发调用时，如果缓存没有做好隔离，就可能出现 A 请求的数据被 B 请求读到的情况。

解决方式有两种：一是让 skill 完全无状态，所有需要的数据都从外部存储读取，skill 本身不维护任何跨请求的状态；二是如果确实需要缓存，用请求级别的上下文来隔离，每个请求有独立的缓存实例。在 GKE 上部署时，还要注意多个 Pod 之间的状态同步问题，如果 skill 有本地缓存，不同 Pod 的缓存可能不一致，这种情况要么改用集中式缓存，要么接受最终一致性。

5.4 版本管理：skill 变更如何不破坏现有 Agent

Skill 一旦被多个 Agent 依赖，变更就要非常谨慎。我遇到过因为修改了一个 skill 的输出字段名，导致依赖它的三个 Agent 全部报错的情况。后来我们建立了一套 skill 版本管理规范：任何破坏性的变更都必须通过新增版本的方式来做，旧版本保留一段时间。

具体做法是在 skill 名称或者路由里带上版本号，比如order-query-v1和order-query-v2并存。Agent 在配置里指定使用哪个版本，迁移可以逐步进行。等所有 Agent 都迁移到新版本后，再下线旧版本。这个过程虽然麻烦，但能避免"改一个 skill 炸一片 Agent"的事故。

6. 让 skills 真正可复用的组织与治理思路

6.1 建立 skill 目录和检索机制

当 skill 数量增长到几十个的时候，怎么让开发者和 Agent 快速找到需要的 skill 就成了一个问题。我们的做法是建立一个中心化的 skill 目录，每个 skill 注册时提供元数据，包括名称、描述、输入输出 schema、所属分类、维护者、版本号。

这个目录可以是一个简单的配置文件，也可以是一个独立的服务。关键是它要能被程序化地查询，这样 Agent 在运行时可以根据任务需求动态检索可用的 skill。检索可以基于关键词匹配，也可以基于向量相似度，后者在 skill 描述语义丰富的情况下效果更好。

6.2 skill 的质量评估维度

不是所有 skill 都值得长期维护。我们内部有一套简单的评估维度，用来决定一个 skill 是继续投入还是下线。主要看几个指标：调用频率（太低说明没人用）、错误率（太高说明实现有问题）、复用广度（被多少个 Agent 使用）、维护成本（依赖的外部服务是否稳定）。

定期做一次这样的评估，把低价值的 skill 清理掉，能让整个 skill 库保持精简和健康。我见过一些团队因为只增不减，skill 库膨胀到几百个，最后连维护者自己都搞不清楚哪些还在用。

6.3 安全边界：skill 能访问什么、不能访问什么

Skill 作为 Agent 的能力延伸，它的权限边界直接决定了 Agent 能做什么。一个查询订单的 skill 不应该有修改订单的权限，一个读取公开数据的 skill 不应该能访问用户隐私数据。这个原则听起来简单，但在实际开发中很容易被打破，因为开发者为了图方便，经常会给 skill 过大的权限。

我的建议是最小权限原则要贯彻到每个 skill**。每个 skill 只申请它完成本职工作所必需的最小权限，权限的授予通过配置来管理，而不是硬编码在代码里。这样当需要审计或者收紧权限时，改配置就行，不用改代码重新部署。

7. 关于 skills 这件事，我的一些真实体会

做了一段时间的 Agent Skills 开发，最大的感受是：技术上的难点其实不多，难的是边界划分和约定。写一个能跑的 skill 可能半小时就够了，但要写一个能被多个 Agent 稳定复用、长期维护的 skill，需要考虑的东西就多了去了。输入输出怎么定义、异常怎么处理、版本怎么管理、权限怎么控制，每一个都是需要提前想清楚的问题。

另一个体会是，skills 的粒度没有标准答案。同样一个业务能力，拆成三个 skill 还是合成一个 skill，取决于你的 Agent 怎么用、复用场景有多少、维护团队怎么分工。我见过拆得太细导致 Agent 需要串联五六个 skill 才能完成一个任务的情况，也见过合得太粗导致一个 skill 承担了十几种不同职责的情况。找到适合自己团队的粒度，比照搬别人的方案更重要。

最后说一个我觉得挺有意思的点。Skills 这个概念之所以现在这么热，本质上是因为 Agent 开发正在从"每个 Agent 各写各的"走向"能力共享和复用"。这个趋势和当年微服务从单体里拆分出来的逻辑很像，都是把可复用的能力独立出来，通过标准化的接口来组合。如果你正在做 Agent 相关的开发，早点把 skill 这层抽象建立起来，后面会省很多事。等 Agent 数量多了再回头重构，成本会高得多。