Agent Skills 实战：从设计到 GKE 部署的 AI 智能体能力扩展指南

1. 从“skills”这个标题说起：它到底指什么

第一次看到“skills”这个标题，很多人会以为是某个泛泛而谈的能力清单，或者一份简历上的技能罗列。但结合热搜词里的 Agent Skills、Google Cloud、GKE、Genkit 这些关键词，基本可以确定，这里说的 skills 不是人类的能力项，而是给 AI Agent 使用的可插拔能力模块——一套让智能体从“只会聊天”变成“能干活”的扩展机制。

我把它理解成给 Agent 装的“技能包”。一个裸的 Agent 就像刚入职的实习生，脑子好使但什么工具都不会用；装上 skills 之后，它才知道怎么查数据库、怎么调接口、怎么生成一份分镜脚本、怎么跑一次代码审查。每个 skill 本质上是一段被结构化描述的能力封装，包含触发条件、输入输出定义、执行逻辑，以及最关键的——什么时候该用它。

这套东西解决的核心问题是：Agent 的能力边界不该写死在模型里，而应该像插件一样按需加载。你不可能把所有工具都塞进一次对话的上下文里，那样既浪费 token 又容易让模型犯迷糊。skills 的思路是把能力拆成独立单元，Agent 根据当前任务动态挑选需要的 skill 来用。

适合读这篇的人有三类：一是正在做 Agent 应用开发、想让自己的智能体真正落地干活的工程师；二是用 Google Cloud 那套技术栈（GKE、Genkit）搭 AI 服务、需要给 Agent 扩展能力的后端同学；三是好奇 Agent Skills 到底怎么设计、想自己写一个 skill 试试水的技术爱好者。不管你是哪一类，下面这些内容都能直接拿去参考。

2. Agent Skills 的整体设计思路拆解

2.1 为什么要把能力做成“技能”而不是硬编码

先说一个我踩过的坑。早期做 Agent 项目时，我习惯把所有工具函数写在一个大文件里，Agent 启动时全部注册进去。结果工具一多，模型在选择时就开始犯糊涂——明明该调天气接口，它去调了日历；明明要查订单，它去发了邮件。后来才明白，工具的数量和模型的决策准确率是反相关的，塞得越多，选错的概率越高。

skills 这套机制的核心价值就在这儿：它把能力做了分层和按需加载。Agent 在规划阶段先判断“这个任务需要哪类能力”，然后只把相关的 skill 加载进上下文。这就像你修水管时只打开工具箱里的扳手那一格，而不是把整个工具箱倒在地上。

另一个好处是可维护性。每个 skill 独立成包，有自己的版本、依赖和测试用例。改一个 skill 不会影响其他 skill，团队里不同人也能并行开发不同的技能包。这在多人协作的 Agent 项目里太重要了，我见过太多因为工具函数互相耦合导致改一处崩三处的案例。

2.2 skills 的典型结构长什么样

一个规范的 skill 通常包含几个部分，我用最常见的描述文件形式来说明：

• 元信息：名称、版本、作者、一句话描述。描述要写得让模型能看懂“这个技能是干嘛的”，因为它就是靠这段文字来判断要不要用的。
• 触发条件：什么情况下该激活这个 skill。可以是关键词匹配，也可以是语义判断，好的设计会两者结合。
• 输入参数定义：每个参数的类型、是否必填、含义说明。这部分直接决定模型能不能正确填参。
• 执行逻辑：真正干活的代码，可能是一个函数、一次 API 调用，或者一段提示词模板。
• 输出格式：返回结果的结构，最好固定成模型容易解析的格式。

我个人的经验是，元信息里的描述文字比代码本身还重要。因为模型选不选这个 skill，八成看的是描述写得清不清楚。描述里要包含“什么时候用”和“能解决什么问题”，而不是只写“这是一个查询工具”这种废话。

2.3 和 Google Cloud、GKE、Genkit 的关系

热搜词里出现 GKE 和 Genkit 不是偶然。Genkit 是 Google 推出的 AI 应用开发框架，它天然支持把能力封装成可调用的工具或流程；而 GKE 提供的是运行环境——你的 Agent 和它的 skills 最终要跑在某个地方，容器化部署到 GKE 是很自然的选择。

这三者的组合逻辑是这样的：Genkit 负责定义和编排 skills，GKE 负责承载和扩缩容。当你的 Agent 需要处理高并发请求时，skills 作为独立服务部署在 GKE 上，可以单独扩容。比如“图像生成”这个 skill 特别吃资源，那就只给它多开几个副本，其他轻量 skill 不用跟着扩。这种细粒度的资源调度，是单体 Agent 做不到的。

2.4 方案选型时我考虑的几个维度

在决定用 skills 架构之前，我对比过几种方案，这里把考量维度列出来供参考：

选 skills 架构的临界点，我的经验是工具数量超过 10 个、或者团队超过 3 个人同时开发工具时，收益就开始明显超过成本了。低于这个规模，硬编码反而更省事。

3. 核心细节解析与实操要点

3.1 描述文件怎么写才能让模型选对技能

这是整个 skills 体系里最容易被低估的环节。我见过太多人把描述写成“查询用户信息”，然后抱怨模型老是不调用它。问题出在描述太抽象，模型没法判断“什么时候该用”。

好的描述应该包含三个要素：场景、动作、结果。举个例子对比一下：

• 差的写法：“用户查询工具”
• 好的写法：“当用户询问自己的账户余额、订单状态或个人信息时使用。输入用户 ID，返回对应的账户数据。”

第二种写法里，“当用户询问……”是场景，“输入用户 ID”是动作，“返回账户数据”是结果。模型看到这段文字，就能在合适的时机准确激活它。

还有一个技巧是在描述里加入反例。比如“这个技能用于查询订单，不用于修改订单”。明确划出边界，能显著降低误触发的概率。我在一个电商 Agent 项目里加了反例说明后，误调用率从 18% 降到了 6% 左右。

3.2 参数定义里的坑：类型和必填项

参数定义看起来简单，实际上坑很多。最常见的错误是类型定义太宽泛。比如把一个日期参数定义成字符串，模型就可能传“明天”“下周三”这种自然语言进来，而你的代码期望的是“2024-01-15”这种格式。

我的做法是：能用枚举就不用字符串，能用数字就不用字符串，日期一律用 ISO 格式并在描述里写明示例。对于必填参数，一定要在描述里说清楚“不提供这个参数会怎样”，让模型知道缺失的后果。

另一个细节是默认值的处理。有些参数不传时应该有合理默认值，比如分页大小默认 20。这个默认值要写在描述里，否则模型可能每次都显式传一个值，浪费 token。

3.3 执行逻辑的隔离与超时控制

每个 skill 的执行逻辑必须是隔离的。我吃过亏：一个 skill 里的数据库连接池被耗尽，导致整个 Agent 所有技能都卡死。后来改成每个 skill 独立管理自己的资源，并且强制设置超时。

超时时间怎么定？我的经验值是普通查询类 skill 设 5 秒，涉及外部 API 的设 10 秒，生成类任务设 30 秒。超过就返回超时错误，让 Agent 决定是重试还是换方案。千万别让一个 skill 无限期挂着，那会拖垮整个对话。

还有一点是错误信息的处理。skill 执行失败时，返回给模型的错误信息要既简洁又有指导性。比如不要返回“Error 500”，而是返回“订单查询服务暂时不可用，建议稍后重试或引导用户联系客服”。这样模型才能做出合理的后续决策。

3.4 版本管理与灰度发布

skills 是要迭代的，但直接替换线上版本风险很大。我的做法是每个 skill 支持多版本共存，通过配置决定当前激活哪个版本。新版本先在小流量上跑，观察调用成功率和模型选择准确率，没问题再全量。

具体操作上，我会在 skill 的元信息里加一个version字段，加载器根据配置读取对应版本。灰度期间同时加载新旧两个版本，但只有配置指定的那个会被注册给 Agent。这样回滚只需要改一行配置，不用重新部署。

注意：多版本共存时，描述文字要有所区分，否则模型可能在新旧版本之间随机选择，导致行为不一致。我通常会在灰度版本的描述末尾加一个标记，但正式发布前一定要去掉。

4. 实操过程与核心环节实现

4.1 从零搭建一个 skill 的完整流程

假设我们要做一个“查询天气”的 skill，跑在 Genkit 框架上，最终部署到 GKE。完整流程分六步。

第一步，定义 skill 的元信息。创建一个描述文件，包含名称get_weather、版本1.0.0、描述“当用户询问某个城市的天气情况时使用。输入城市名称，返回当前温度和天气状况。”触发条件设为语义匹配“天气”“气温”“下雨”等意图。

第二步，定义输入参数。这里只需要一个参数city，类型字符串，必填，描述为“城市名称，例如北京、上海”。我特意在描述里加了示例，实测能减少模型传错格式的概率。

第三步，编写执行逻辑。用 Genkit 的 tool 定义方式包裹一个异步函数，内部调用天气 API。关键点是设置 8 秒超时，并且对 API 返回做归一化处理——不同天气源返回的字段名不一样，统一成temperature和condition两个字段再返回。

第四步，定义输出格式。返回一个固定结构的对象，包含city、temperature、condition、updated_at。固定结构的好处是模型解析起来稳定，不会因为字段缺失而胡编。

第五步，本地测试。写几个测试用例：正常城市名、不存在的城市、API 超时。观察模型在不同输入下是否正确调用，以及错误情况下是否给出合理回复。

第六步，打包部署。把 skill 打成容器镜像，推到镜像仓库，然后在 GKE 上以 Deployment 形式部署。配置好资源限制和健康检查，确保单个 skill 挂掉不影响其他技能。

4.2 参数计算与选择：超时和重试怎么定

超时和重试这两个参数，拍脑袋定很容易出问题。我的计算逻辑是这样的：

先测出 skill 在正常情况下的 P95 耗时，比如天气查询是 1.2 秒。然后超时时间设为 P95 的 3 到 4 倍，也就是 4 到 5 秒，留出网络波动的余量。重试次数设为 1 次，因为天气查询是幂等的，重试没有副作用。但如果是“下单”这种非幂等操作，重试次数必须是 0，否则会重复下单。

重试的间隔也要注意。我一般用指数退避，第一次等 500 毫秒，第二次等 1 秒。但总重试时间不能超过超时时间，否则重试还没跑完就被超时掐断了。

对于生成类 skill，比如“生成分镜脚本”，超时要放宽到 30 秒甚至 60 秒，因为大模型生成本身就需要时间。这种情况下重试要谨慎，因为重试意味着重新生成，成本很高。我的做法是生成类 skill 不自动重试，而是把失败信息返回给 Agent，让它决定是换个提示词重试还是告知用户。

4.3 在 GKE 上部署 skills 的配置要点

把 skills 部署到 GKE 时，有几个配置项直接影响稳定性。

资源请求和限制要设合理。我一般给每个 skill 容器设 256Mi 内存请求、512Mi 限制，CPU 设 100m 请求、500m 限制。生成类 skill 内存要翻倍。设得太小会被 OOM Kill，设得太大浪费资源。

健康检查分两种：liveness 探针检查进程是否活着，readiness 探针检查是否准备好接收请求。readiness 探针要等 skill 完成初始化（比如加载模型、建立连接池）之后再返回成功，否则流量打进来会报错。

水平扩缩容用 HPA，基于 CPU 使用率触发。我设的阈值是 70%，最小副本 2 个，最大 10 个。最小设 2 是为了保证高可用，一个挂了另一个还能顶。

配置管理用 ConfigMap 存 skill 的激活版本和参数，用 Secret 存 API 密钥。这样改配置不用重新打镜像，滚动更新就行。

4.4 一次完整的调用链路追踪

当 Agent 决定调用某个 skill 时，背后发生的事比想象中多。我以一次天气查询为例，把链路拆开：

1. Agent 解析用户输入“北京今天天气怎么样”，识别出天气查询意图。
2. 加载器根据意图匹配到get_weatherskill，把它的描述和参数定义注入上下文。
3. 模型生成调用请求，参数为{city: "北京"}。
4. 执行器校验参数，通过后调用 skill 函数。
5. skill 函数请求天气 API，拿到原始数据。
6. 数据归一化后返回给执行器。
7. 执行器把结果格式化，回传给模型。
8. 模型根据结果生成自然语言回复。

这条链路里，第 2 步和第 7 步是最容易出问题的。第 2 步如果匹配错了 skill，后面全错；第 7 步如果格式不对，模型可能解析失败。所以我会在这两个环节加详细的日志，方便排查。

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

5.1 模型不调用 skill 怎么办

这是最高频的问题。排查顺序我总结成一张表：

我遇到最多的是描述太抽象。有一次一个“发送邮件”的 skill 死活不被调用，后来发现描述写的是“邮件相关操作”，模型根本不知道什么时候该用。改成“当用户明确要求发送邮件通知某人时使用”之后，立刻就正常了。

5.2 skill 执行超时或报错怎么处理

超时和报错要分开处理。超时通常是外部依赖慢，报错可能是参数问题或服务故障。

对于超时，我的处理策略是：第一次超时返回友好提示，让 Agent 决定是否重试。如果 Agent 选择重试且再次超时，就明确告知用户“服务暂时繁忙”。不要无限重试，那只会让用户等更久。

对于报错，关键是错误信息要能被模型理解。我见过有人直接把异常堆栈返回给模型，模型完全懵了。正确的做法是把错误分类，返回结构化的错误码和人类可读的说明。比如{code: "INVALID_CITY", message: "未找到该城市，请检查城市名称是否正确"}。

还有一个隐藏坑是参数校验失败。模型有时候会传一些奇怪的参数，比如把城市名传成“北京天气”。这时候 skill 要能识别并返回明确的纠正提示，而不是直接报错。我在参数校验里加了一层清洗逻辑，去掉常见的冗余词。

5.3 skill 之间互相干扰怎么排查

当 skill 数量多了之后，会出现一些诡异现象：明明该调 A，结果调了 B；或者 A 和 B 都被调用了。这通常是描述重叠或上下文污染导致的。

排查方法是逐个隔离测试。先把其他 skill 全部禁用，只留一个，看是否正常。然后逐步加回来，观察什么时候开始出问题。找到冲突的两个 skill 后，对比它们的描述，找出重叠的触发词，然后修改描述划清边界。

另一个原因是上下文里残留了上一个 skill 的输出。比如用户先问了天气，Agent 调了天气 skill，然后用户问“那明天呢”，这时候上下文里还有天气 skill 的信息，可能导致误调用。解决办法是在每轮对话后清理不再需要的 skill 上下文，只保留当前活跃的。

5.4 性能瓶颈定位与优化

skills 架构的性能瓶颈通常出现在三个地方：加载、执行、序列化。

加载慢的表现是首次调用延迟高。原因是 skill 描述文件大、或者初始化逻辑重。优化方法是懒加载——只在真正需要时才初始化 skill 的重资源，比如数据库连接。

执行慢就是 skill 本身的逻辑问题。用 profiling 工具找到耗时最长的函数，针对性优化。我遇到过一个 skill 因为每次调用都重新建立 HTTP 连接，导致耗时 2 秒多，改成连接池后降到 200 毫秒。

序列化慢容易被忽略。如果 skill 返回的数据结构特别大，序列化和反序列化会吃掉不少时间。解决办法是只返回必要字段，别把整个数据库记录都塞回去。

实操心得：我习惯给每个 skill 加一个耗时打点，记录加载时间、执行时间、序列化时间。这样出问题时一眼就能看出瓶颈在哪，不用瞎猜。

5.5 安全与权限控制

skills 能干活，也意味着能闯祸。一个没有权限控制的 skill 可能被诱导执行危险操作。我的做法是每个 skill 声明自己需要的权限，执行前校验当前会话是否有对应权限。

比如“删除文件”这个 skill 需要file:delete权限，如果当前用户没有，直接拒绝，不进入执行逻辑。权限校验要在 skill 内部做，不能只靠 Agent 判断，因为 Agent 可能被提示词注入攻击绕过。

另一个措施是敏感操作的二次确认。对于删除、支付、发送这类不可逆操作，skill 执行前要返回一个确认请求，等用户明确同意后再执行。这个确认流程要写在 skill 逻辑里，不能依赖模型自觉。

6. 进阶玩法：让 skills 组合出更强能力

6.1 skill 编排与流水线

单个 skill 能力有限，但组合起来就能干大事。比如“生成分镜脚本”这个需求，可以拆成三个 skill：analyze_script分析剧本结构、generate_shots生成分镜描述、format_output格式化输出。Agent 按顺序调用这三个 skill，就完成了一个完整流程。

编排的关键是定义清楚 skill 之间的数据契约。前一个 skill 的输出格式，必须和后一个 skill 的输入格式对得上。我一般会定义一个中间数据结构，所有 skill 都按这个结构来传数据，避免格式不匹配。

Genkit 在这方面提供了不错的支持，它可以把多个 tool 串成 flow，自动处理数据传递。但我的建议是不要过度编排，超过五个 skill 的流水线就很难调试了。该合并的合并，该拆分的拆分，保持每个流程在可控范围内。

6.2 动态生成 skill

更进阶的玩法是让 Agent 自己生成 skill。当遇到一个从未见过的任务时，Agent 可以写一段代码，封装成临时 skill 来执行。这听起来很科幻，但技术上已经可行。

我的实践是限制动态 skill 的能力范围。只允许它调用预定义的安全 API，不能执行任意代码。生成的 skill 要经过静态检查，确认没有危险操作后才能执行。执行完就丢弃，不持久化。

这个玩法适合处理一次性的、格式固定的任务，比如“把这个 JSON 转成表格”。但涉及敏感数据或不可逆操作时，绝对不能用动态 skill，风险太大。

6.3 skills 的测试策略

skills 的测试比普通函数复杂，因为要测两层：skill 本身逻辑对不对，以及模型会不会正确调用它。

第一层用常规单元测试就行，mock 掉外部依赖，验证输入输出。第二层需要构造对话场景，观察模型的选择行为。我会准备一组测试用例，每个用例包含用户输入和期望调用的 skill，然后跑批量测试，统计准确率。

准确率低于 90% 就要排查。常见原因是描述不够清晰，或者测试用例本身有歧义。我一般会把准确率目标定在 95% 以上，低于这个值就说明 skill 的设计有问题。

注意：测试用例要覆盖边界情况，比如用户输入很模糊、同时涉及多个 skill、或者包含干扰信息。这些才是真实场景里最容易出问题的地方。

7. 我在实际项目里踩过的坑

说几个印象深刻的教训。第一个是描述文件里的标点符号。有次一个 skill 死活不被调用，排查了半天发现描述里用了中文全角逗号，而匹配逻辑用的是半角。这种细节问题最折磨人，后来我加了格式校验，描述文件必须通过 lint 才能发布。

第二个是版本兼容性。我升级了一个 skill 的参数定义，但忘了更新依赖它的编排流程，结果线上直接报错。从那以后，我给每个 skill 加了版本号，编排流程里明确指定依赖的版本，不兼容的升级必须同步改编排。

第三个是日志太多反而找不到问题。早期我给每个 skill 都打了详细日志，结果出问题时日志刷屏，根本看不过来。后来改成分级日志，正常调用只记一行摘要，出错时才打详细堆栈。这样排查效率高多了。

最后一个体会是，skills 的数量要克制。我见过一个项目塞了 50 多个 skill，结果模型选择准确率惨不忍睹。后来砍到 15 个，把一些低频 skill 合并或下线，准确率立刻回升。skill 不是越多越好，够用就行，每个都要有明确的不可替代的价值。

如果你也在做 Agent Skills 相关的东西，我的建议是先从两三个核心 skill 做起，把描述、参数、错误处理这些基础打扎实，再逐步扩展。别一上来就追求大而全，那只会让你陷入调试的泥潭。