1. 从skills这个标题说起Agent Skills 到底在解决什么问题第一次看到skills这个标题很多人会以为是某个技能树、能力清单或者培训课程。但结合热搜词里的 Agent Skills、Google Cloud、GKE、Genkit、Gemini 来看这里的 skills 指向的是一个更具体的东西给 AI Agent 装配可复用、可组合、可独立部署的能力单元。换句话说它不是教人怎么用 AI而是教开发者怎么把一个 Agent 能干什么这件事拆成一块块可以插拔的积木。我在实际接触这类项目时最大的感受是大部分人做 Agent 的第一反应是写一个巨大的 prompt把所有能力塞进一段系统提示里然后祈祷模型每次都能正确调用。这种做法在 demo 阶段没问题一旦要上线、要多人协作、要迭代就会迅速崩掉。Agent Skills 这套思路的核心价值就是把这个巨型 prompt拆解成一个个独立的 skill每个 skill 有自己的描述、输入输出契约、执行逻辑Agent 在运行时根据任务动态选择调用哪个 skill。这个项目适合谁看三类人最需要第一类是正在用 Gemini 或类似大模型做 Agent 应用、但被 prompt 维护成本折磨的开发者第二类是想把 Agent 部署到 Google Cloud 上、需要一套工程化能力管理方案的团队第三类是刚接触 Genkit 这类框架、想搞清楚skill 和 tool 到底有什么区别的入门者。我会从概念拆解、框架选型、落地步骤、踩坑经验几个角度把这件事讲透。需要先明确一个前提Agent Skills 不是某个单一产品的名字而是一种架构模式。Google 在 Genkit 和 Gemini 生态里推的这套东西本质上是把函数调用function calling进一步抽象成技能注册与发现。理解这一点后面所有的工程细节才站得住脚。2. Skill、Tool、Function 三者到底差在哪2.1 从一次真实的调用链说起假设你做一个帮我订会议室的 Agent。用户说下周三下午两点帮我订个能坐 8 个人的会议室。这条指令背后Agent 需要做几件事解析时间、查询可用会议室、检查人数容量、执行预订、返回确认。如果把这些都写成一个 tool那这个 tool 会非常臃肿参数一大堆模型很容易填错。Agent Skills 的做法是拆开一个parse_timeskill 负责把自然语言时间转成结构化时间一个query_roomskill 负责按条件查会议室一个book_roomskill 负责执行预订。每个 skill 只做一件事参数少、语义清晰模型调用时的准确率会明显提升。这就是 skill 和 tool 最直观的区别——tool 是能力接口skill 是能力单元一个 tool 可以内部编排多个 skill也可以一个 skill 直接暴露成一个 tool。再往深一层function 是编程语言层面的概念是 skill 的实现载体。你写一个 Python 函数用 Genkit 的装饰器把它注册成 skill框架再把它暴露给模型作为可调用的 tool。三者是实现 → 注册 → 暴露的递进关系不是并列关系。很多人搞混是因为文档里经常混用这几个词。2.2 为什么可发现性是 skill 设计的命门Skill 和普通函数最大的不同在于它必须能被 Agent自动发现并正确选择。这就引出一个关键设计点每个 skill 都需要一份高质量的元数据描述包括它叫什么、干什么、什么时候该用、输入输出长什么样。这份描述直接决定了模型能不能在几十个 skill 里挑对那一个。我踩过的坑是早期给 skill 写的描述太笼统比如处理用户请求结果模型在多个 skill 之间反复横跳调用链乱成一团。后来改成当用户提供自然语言时间表达如下周三下午两点时将其转换为 ISO 8601 格式的时间对象准确率立刻上来了。skill 描述要写得像给一个新同事交代任务具体到触发条件和边界这是最容易被忽视但最影响效果的一环。2.3 一张表看清三者的边界维度FunctionSkillTool本质代码实现能力单元 元数据暴露给模型的接口关注点逻辑正确可发现、可组合参数契约粒度任意单一职责可粗可细谁消费开发者Agent 运行时大模型典型数量无限制中等10-50少而精这张表是我自己在做架构评审时常用的对照工具。核心结论是skill 的数量可以比 tool 多但每个 skill 必须足够窄。窄意味着模型选择时的歧义小组合时的灵活性高。3. 用 Genkit 把 skill 跑起来环境到第一个可用 Agent3.1 环境准备里最容易被忽略的两件事Genkit 的安装本身不复杂npm install -g genkit或者用项目级依赖都行。但有两个细节新手几乎必踩。第一是运行时版本Genkit 对 Node 版本有要求版本太低会在初始化时报一些看不懂的模块错误建议直接用当前 LTS。第二是模型访问凭证的配置方式很多人把密钥硬编码在代码里这在本地跑没问题一上 GKE 就出安全事故。正确做法是用环境变量或云平台的密钥管理服务代码里只读不写。我建议在动手写 skill 之前先跑通一个最小的hello agent确认模型能正常响应。这一步能帮你排除掉 80% 的环境问题避免后面把环境问题和逻辑问题混在一起排查。3.2 定义第一个 skill 的完整流程一个 skill 的定义通常包含四部分名称、描述、输入 schema、执行函数。用 Genkit 的风格大致是这样import { genkit, z } from genkit; import { googleAI } from genkit-ai/googleai; const ai genkit({ plugins: [googleAI()] }); const parseTimeSkill ai.defineTool( { name: parseTime, description: 将自然语言时间表达转换为 ISO 8601 时间对象例如下周三下午两点, inputSchema: z.object({ text: z.string() }), outputSchema: z.object({ iso: z.string() }), }, async ({ text }) { // 实际解析逻辑可调用模型或规则引擎 return { iso: 2025-01-08T14:00:0008:00 }; } );注意description的写法——它同时是给模型看的使用说明也是给人看的文档。我习惯把触发条件写在最前面因为模型在选择 skill 时最先匹配的就是这部分语义。3.3 让 Agent 真正会用这些 skill定义完 skill 只是第一步关键是让 Agent 在对话中自动调用。Genkit 的generate接口支持传入 tools 数组模型会根据用户输入决定是否调用、调用哪个。这里有个实操技巧先用少量 skill 验证调用链再逐步增加。一次性塞 20 个 skill 进去模型的选择准确率会断崖式下降而且你很难定位是哪个 skill 的描述有问题。验证时我习惯打开 Genkit 的开发者 UI它能可视化展示每一次调用的输入输出和决策路径。这个 UI 在排查模型为什么没调用我预期的 skill时特别有用比看日志高效得多。3.4 从本地到 GKE 的部署差异本地跑通不代表能上生产。部署到 GKE 时几个点必须提前处理skill 执行函数如果是 IO 密集型的要考虑并发和超时模型调用有配额限制要做限流和降级日志要结构化方便在云平台上检索。我见过太多项目本地 demo 完美一上集群就因为超时和配额问题频繁失败。提示在 GKE 上部署 Agent 服务时建议把 skill 执行和模型调用分成两个独立的服务这样模型侧扩容和 skill 侧扩容可以解耦成本也更可控。4. Skill 编排当单个 skill 不够用时怎么办4.1 编排的两种思路链式与路由单个 skill 只能解决原子任务真实业务往往是多步的。编排有两种主流思路。链式编排是把 skill 按固定顺序串起来前一个的输出是后一个的输入适合流程确定的场景比如解析时间 → 查会议室 → 预订。路由编排是先判断任务类型再分发给对应的 skill 子集适合任务类型多样的场景比如一个客服 Agent 要同时处理退款、查询、投诉。选择哪种取决于你的任务是否可预测。可预测就用链式简单可靠不可预测就用路由灵活但需要更强的意图识别能力。我个人的经验是能用链式就别用路由因为链式的调试成本低得多每一步的输入输出都是确定的。4.2 用 Genkit Flow 固化编排逻辑Genkit 提供了 Flow 的概念可以把一段编排逻辑封装成一个可复用、可观测的单元。这比在 prompt 里让模型自己决定调用顺序要可靠得多。下面是一个链式编排的简化示例import { defineFlow } from genkit-ai/flow; export const bookRoomFlow defineFlow( { name: bookRoom }, async (userInput) { const time await parseTimeSkill({ text: userInput }); const rooms await queryRoomSkill({ time: time.iso, capacity: 8 }); if (rooms.length 0) return { status: no_room }; return await bookRoomSkill({ roomId: rooms[0].id, time: time.iso }); } );Flow 的好处是它把编排逻辑从模型决策变成了代码决策确定性和可测试性都大幅提升。模型只负责它擅长的部分——理解自然语言剩下的交给代码。4.3 编排中的错误处理与重试多步编排里任何一步都可能失败。我的做法是给每个 skill 定义明确的错误类型编排层根据错误类型决定是重试、降级还是直接返回。比如查询会议室超时可以重试一次预订失败则必须返回明确原因不能静默吞掉。这里有个反直觉的点不要让模型来决定重试。模型对失败的理解往往不准确它可能把一次正常的空结果当成失败去重试浪费配额。重试逻辑应该写在代码里模型只负责生成最终的用户回复。5. 那些文档不会告诉你的踩坑记录5.1 skill 描述写得太聪明反而坏事我一开始喜欢在 skill 描述里写很多高级的语义比如智能识别用户意图并优雅处理。结果模型完全抓不住重点。后来改成大白话把触发条件、输入格式、输出格式一条条列清楚效果立竿见影。给模型看的描述要像给机器看的规格说明不要像给人类看的营销文案。5.2 参数 schema 太宽松导致模型乱填用z.string()这种宽松类型时模型经常填出意料之外的值。比如时间参数它可能填下午而不是具体时间。解决办法是尽量用枚举、正则约束、必填校验把 schema 收紧。schema 越严格模型犯错的空间越小。这一点和传统 API 设计是相通的——契约越明确调用方越不容易出错。5.3 本地能跑、线上报错的典型原因最常见的是环境变量缺失和网络策略限制。本地开发时你可能直接用了个人凭证线上服务账号没有对应权限调用就失败了。排查这类问题第一步永远是看服务账号的权限和网络出口策略而不是怀疑代码逻辑。5.4 关于 Gemini 账号资格问题的说明热搜里出现了your account is not eligible for gemini code assist for individuals at this time这类词说明不少人在配置阶段卡在了账号资格上。这类问题通常和账号类型、地区、订阅状态有关。我的建议是先确认你使用的账号类型是否符合对应服务的要求再检查是否需要通过组织管理员开通权限。遇到资格提示时不要反复重试先去看官方文档里关于账号类型和可用区域的说明能省下大量时间。6. 把 skills 做成可维护资产命名、版本与测试6.1 命名规范决定团队协作效率Skill 一多命名混乱就是灾难。我坚持的规范是动词开头、领域前缀、语义唯一。比如room.queryAvailable、room.book、time.parse。这样在几十个 skill 里检索和归类都很清晰。避免用handle、process这种万能动词它们等于没命名。6.2 给 skill 加版本别怕麻烦Skill 的描述和 schema 一旦变更模型的行为可能跟着变。给 skill 加版本号如room.book.v2可以在不影响线上 Agent 的前提下灰度测试新版本。这个习惯在多人协作时尤其重要否则你改一个描述别人的 Agent 可能就崩了。6.3 测试 skill 的三个层次第一层是单元测试验证执行函数的逻辑正确第二层是契约测试验证输入输出符合 schema第三层是调用测试用真实或模拟的模型输入验证模型能否正确选中这个 skill。第三层最容易被忽略但恰恰是 Agent 场景下最关键的。我通常会准备一组意图样本每次改动 skill 描述后跑一遍看选中率有没有下降。测试层次验证目标工具建议单元测试执行逻辑正确常规测试框架契约测试schema 合规schema 校验库调用测试模型选中率意图样本集 自动化6.4 监控上线后的 skill 表现上线不是终点。要监控每个 skill 的调用频次、成功率、平均耗时以及未被调用但预期应被调用的情况。后者往往意味着描述有问题。我习惯每周看一次 skill 调用分布异常波动通常能提前暴露问题。7. 我对 Agent Skills 这套模式的实际体会做了几个基于 Genkit 和 Gemini 的 Agent 项目之后我最大的体会是Agent 的可靠性不取决于模型多强而取决于你把能力拆得多清楚。模型再聪明面对一个描述模糊、职责不清的 skill 集合也会表现得像个新手。反过来即使模型能力一般只要 skill 设计得当、编排逻辑清晰整体表现也能很稳。另一个体会是关于克制。刚开始做 Agent 的人总想让它什么都能干于是不断加 skill、加能力。但每加一个 skill模型的选择负担就增加一分。我现在更倾向于先做减法这个 skill 能不能合并这个能力是不是根本不需要少而精的 skill 集合比大而全的能力库更容易维护也更容易调优。最后分享一个实用习惯把每个 skill 的设计意图和已知边界写在一个单独的文档里和代码放在一起。半年后你回头看或者新人接手时这份文档比任何注释都值钱。Agent 项目迭代快唯一能对抗遗忘的就是当时留下的清晰记录。