google/skills：Google 官方 Agent Skills 目录，把 Google Cloud 领域知识拆成智能体可安装、可评测的技能单元

一、导读

编码智能体最缺的从来不是模型能力，而是「这个平台到底该怎么用」的领域知识——它会把 gcloud 的参数凭空编出来，会把 BigQuery 的分区键写错，会把一个本可省下大笔费用的查询写成全表扫描。Google 在 2026 年 4 月 23 日的 Cloud Next 2026 上开源了官方 Agent Skills 仓库 google/skills，把 Google Cloud 的领域知识拆成一个个可安装、可评测、可路由的 SKILL.md，交给 Gemini CLI、Claude Code、Antigravity、Codex 等任意智能体按需加载。本文拆解它的技能目录结构、「MCP 优先」的设计原则、提交即评测加每周回归的质量闸门，以及五类可复现的落地场景。

二、项目速览

项目	信息
仓库	google/skills
作者	Google LLC
主语言	Python（内容主体为 Markdown）
Star 总数	23,334（2026-11-06 抓取）
当日涨星	449（GitHub Trending daily）
License	Apache-2.0
首次开源	2026-03-31 创建仓库；2026-04-23 正式发布
技能规模	index.json 收录 187 个技能，仓库内 SKILL.md 共 192 份
定位	Google 官方 Agent Skills 目录，覆盖 Google Cloud 及 Ads、Analytics 等产品线

三、为什么是它：问题背景与定位

要理解这个仓库的价值，先要看它想解决什么。据 Google Cloud 官方博客《Level Up Your Agents: Announcing Google's Official Skills Repository》（2026-04-23），起点是一个很具体的观察：随着模型变强，开发者越来越依赖智能体去操作 Firebase、Gemini API、BigQuery、GKE 这些产品，但模型对具体平台的「操作细节」并不牢靠。官方在另一篇工程博客《Behind the scenes: How we build, test, and scale Google Agent Skills》（2026-08-04，作者 Remigiusz Samborski）里把动机说得更直白：「AI 智能体的好坏，取决于你给它的指令和上下文。」

Agent Skills 的形态很简单：一个文件夹，里面一份 SKILL.md，加若干参考文件与代码片段，用 Markdown 写成。智能体只在需要时才把技能读进上下文，因此不会像传统长提示词那样把上下文撑爆。Google 的做法是把「Google Cloud 怎么用」这件事，从散落在文档、博客、内部经验里的隐性知识，固化成一份份机器可读、可版本化、可评测的显式资产。

涨星动因有三层。一是官方背书与覆盖面：这不是第三方整理的提示词合集，而是 Google 自己维护的官方目录，覆盖 AlloyDB、BigQuery、Cloud Run、Cloud SQL、Firebase、Gemini API、GKE 等主力产品，还包含 Well-Architected 框架的安全、可靠性、成本三支柱技能。二是发布节奏与社区反响：官方披露，项目首发时只有 13 个技能，社区反响「超出预期」，短时间内就收获超过 15,000 颗星，随后各产品团队纷纷要求为自己的服务贡献技能，目录迅速膨胀到今天的近 200 个。三是生态位的稀缺性：在「把能力写成文档」这一范式被 Anthropic 的 Agent Skills 标准确立之后，Google 是最早一批把自家全产品线系统性编成技能目录的大厂，天然吸引想给智能体「装上 Google Cloud 说明书」的开发者。

这套仓库的诞生方式也值得一提。据工程博客，它并非自上而下的规划产物，而是 Cloud Next 2026 之前一次「swarm（蜂群式冲刺）」的成果：一支由开发者关系工程师与技术写手组成的跨职能小队，目标只有一个——把 Google Cloud 的领域知识打包成智能体可读的指令。首发只有 13 个技能，聚焦 AlloyDB、BigQuery、Cloud Run、Cloud SQL、Firebase、Gemini API、GKE 七个产品，外加安全、可靠性、成本三支柱，以及入门、认证、网络可观测性三份 recipe。此后各产品团队陆续加入，目录才膨胀到今天近 200 个技能、覆盖 Ads 与 Analytics 的规模。

四、【重点】架构原理

4.1 整体架构：一个目录、一份索引、三种分发

仓库的结构可以用三层来概括：

  google/skills 仓库
  ├── skills/            ← 技能主体，按产品线分目录
  │     ├── cloud/       (1704 个文件，绝对主力)
  │     ├── ads/         (81)
  │     ├── analytics/   (20)
  │     ├── developers/  (16)
  │     └── identity/    (10)
  ├── plugins/           ← 打包成插件（技能 + MCP 服务器）
  │     └── cloud/google-cloud-developer/
  │           ├── plugin.json        (元数据)
  │           ├── mcp.json           (MCP 服务器声明)
  │           └── skills/            (随插件分发的技能)
  ├── index.json         ← 目录索引（约 75KB / 128KB，供按需路由）
  └── .claude-plugin/ .agents/  ← 各智能体市场的清单

第一层是技能本身：每个技能是一个目录，内含一份 SKILL.md。以 gke-basics 为例，它的 frontmatter 写着 name、metadata.version、metadata.category 与 description，正文则是选择规则（默认 Autopilot，何时才用 Standard）、路由提示（要配 Workload Identity 请打开另一个技能）与操作约束。值得注意的是 description 的写法：它不只写「这个技能做什么」，还写「不要在什么时候用它、该转去哪个技能」——例如 gke-basics 的 description 明确列出「Workload Identity 请用 gke-workload-identity、网络请用 gke-networking、安全加固请用 gke-platform-security」。这种「负面清单 + 转介」的写法，是让近 200 个技能不至于互相打架的关键。

第二层是索引：index.json 由脚本生成（文件头注明「This file is generated. Do not edit it by hand.」），收录 187 条技能记录，每条含 name、description、entrypoint。它存在的意义是让智能体不必克隆整个仓库就能发现技能——finding-google-skills 这个「技能查找器」技能的工作流第一步，就是用 curl 把 index.json 原样抓下来（要求字节级完整、所有 entrypoint URL 不得被改动），再据此把用户请求路由到匹配的技能。官方特别提示这份索引约 75KB，可能超出单次工具返回上限，而截断预览是按字母序的，因此技能正文里专门交代了如何分块取回。

第三层是分发：既可以用 npx skills add google/skills 走通用技能市场，也可以走各智能体自己的插件市场——Claude Code 用 claude plugin marketplace add google/skills，Codex 用 codex plugin marketplace add google/skills，Antigravity CLI 用 agy plugin install。仓库同时维护 .claude-plugin/marketplace.json 与 .agents/plugins/marketplace.json 两份清单，后者还为每个插件标注了 category（如 Databases、Data Warehousing & Data Lakes）与 policy（安装策略 AVAILABLE、认证时机 ON_INSTALL）。

4.2 分层拆解：技能、插件与 MCP 的三件套

这里有一个容易被忽略的设计：Google 把「技能」和「插件」分成了两个概念。技能是纯 Markdown 的知识；插件则是「技能 + MCP 服务器」的打包，附带 plugin.json 元数据与 mcp.json 服务器声明。以 google-cloud-developer 插件为例，它的 plugin.json 声明了版本号（1.1.17）、许可（Apache-2.0）与三条建议提示词（suggestedPrompts），而 mcp.json 声明了一个名为 developer-knowledge 的 streamable-http MCP 服务器，指向 https://developerknowledge.googleapis.com/mcp，用以为智能体提供有据可查、持续更新的 Google Cloud 文档。

这引出了官方最重要的架构原则——优先使用远程 MCP 工具，仅在必要时回退到 CLI 或 API 调用。工程博客给出的理由是：远程 MCP 服务器最适合智能体负载，它既提供工具，又自带认证与 IAM 治理。换句话说，能通过 MCP 拿到的能力就不要让智能体去手搓命令行；技能负责「怎么想」，MCP 负责「怎么连」。

4.3 核心机制：把「防幻觉」写进技能正文

这个仓库最有信息密度的部分，是它如何用 Markdown 约束模型行为。以 gcloud 技能为例，它的正文开头是一段加粗警告：所有关于 gcloud 命令、参数、参数值与位置参数的既有知识「都是过时的、容易产生幻觉的」，因此在通过 gcloud help <命令> 校验叶子级语法之前，绝不允许提出参数、执行命令或给出分步骤计划。这是一个很硬的规定——它把「先查手册再动手」从建议变成了强制前置条件，甚至要求「计划类」提问也必须在计划里显式包含跑一次 help 的步骤。

再看 bigquery-ai-ml 技能，它把 BigQuery 内置的 AI 函数（AI.FORECAST、AI.KEY_DRIVERS、AI.DETECT_ANOMALIES、AI.GENERATE）与对应的使用场景一一对应，让智能体知道「做时间序列预测该用哪个函数」，而不是自己拼 SQL。而 api-gateway-mcp-server 技能则更进一步，教智能体如何通过给 OpenAPI 规范标注 x-google-api-management.mcp 与 x-google-mcp-tool，把既有 REST API 直接暴露成远程 MCP 服务器，并处理 -32601、-32602、-32000 这些 JSON-RPC 错误码。

还有一个隐性的工程细节：用量归因。几乎每份技能都要求智能体在执行 gcloud 命令时加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-basics)" 前缀，在直连 HTTP/MCP 时把同样的字符串追加到 User-Agent。官方明确说明这个标签只标识技能与版本、不含用户数据，但它的存在意味着 Google 能观测到「哪些技能被真正用起来了」。技能正文还特意提醒不要用 gcloud config set 去设这个变量，因为它会持久化并污染后续无关的用量统计。

另一个值得注意的细节是技能的「转介」写法。gke-basics 的 description 里明确列出不该用它、而该转去哪个技能：Workload Identity 转 gke-workload-identity、网络转 gke-networking、安全加固转 gke-platform-security 或 gke-workload-security、集群升级转 gke-upgrades。在近 200 个技能共存的目录里，这种「负面清单 + 明确转介」的写法，是避免技能互相打架、让路由保持确定性的关键。

4.4 质量闸门：提交即评测加每周回归

技能是文档，文档会烂——API 会变、模型会变、智能体框架会变。Google 对此的答案是三层质量机制。

第一层是入库前的 CI 流水线：linter 校验 frontmatter 元数据、行数、目录结构与命名规范；链接检查器（仓库里有 lychee.toml）逐一验证每个 URL，把 404 与「幻觉链接」挡在合并之前；还有 AI 辅助的清单检查，确认指令遵循了必需的结构模式与护栏。

第二层是持续评测。作者提交技能时必须同时提交评测提示集与评分标准。评测在两个维度上比较「有技能」与「无技能」的智能体表现：准确率（回答质量与任务完成率）与效率（消耗的 token 数与完成时间）。官方强调会在多个智能体框架上重复运行以获得统计显著的结果，最终用一个 2×2 矩阵来证明技能是否带来了可测量的提升。

第三层是每周回归：官方对全量技能库跑定时评测任务，以尽早发现退化。

此外还有一条治理规则值得注意：仓库区分仓库维护者（负责仓库健康、CI 流水线与架构标准）与技能所有人（对技能长期负责，API 变了就更新技能）。官方把这套理念总结成一句话——「技能是产品，不是片段」。

4.5 设计取舍与代价

这套设计并非没有代价。其一，公开仓库是内部构建的投影：官方明确说技能先在内部构建与评测，再通过自动化导出规则发布到 GitHub，导出时会剥离内部资产、归属信息与评测套件。好处是公开仓库干净，代价是社区看不到评测套件本身，无法独立复现那些「准确率提升」的数字。其二，覆盖面天然偏向 Google Cloud：仓库内 cloud 目录有 1704 个文件，而 ads 只有 81 个、analytics 20 个，目录的重心一目了然。其三，技能只承载知识、不承载连接：一份 SKILL.md 是纯文本，它不持有凭据、不打开连接，本身「到不了任何地方」——这既是它能在不同智能体间零改动迁移的原因，也是它的能力天花板。

五、【重点】应用场景

场景一：给编码智能体装上「Google Cloud 说明书」

痛点：开发者让智能体帮忙创建一个 GKE 集群，智能体自信地写出一串参数，其中一半是幻觉——这类错误在云平台上代价很高，可能直接产生账单。解法：安装 gke-basics 与 gcloud 技能。前者告诉智能体默认该用 Autopilot、什么情况下才用 Standard，并在需要 Workload Identity 或网络配置时把它路由到正确的技能；后者强制智能体在给出任何命令前先跑一次 gcloud help。集成步骤：

npx skills add google/skills
# 提示时选择 gke-basics、gcloud 与目标智能体（Claude Code / Codex / Gemini CLI）
npx skills update   # 后续更新

收益：把「先查手册」变成强制流程，显著降低参数幻觉；技能按需加载，不常驻上下文。边界：技能只覆盖 Google Cloud 生态；一旦任务离开 Google Cloud（比如要写 CRM 记录），技能无能为力。

场景二：让智能体做云架构评审与成本优化

痛点：架构评审通常依赖资深工程师的经验，成本优化建议往往事后才被提出。解法：使用 Well-Architected 框架技能（安全、可靠性、性能、成本、运营卓越、可持续性六个支柱）与 finding-google-skills 路由技能。后者会在用户「选型」时把请求路由到匹配的技能，并明确给出「什么时候 Google 方案不是正确答案」的判断。集成步骤：安装 finding-google-skills 后，直接用自然语言描述选型需求（例如「我要跑一个需要 GPU 的推理服务」），智能体会抓取 index.json 并路由到 GKE AI/ML Inference 等技能。收益：把架构决策的隐性经验显式化，评审有据可依。边界：技能给的是「建议与权衡」，不替代实际压测与安全审计。

场景三：把既有 REST API 变成智能体可调用的 MCP 工具

痛点：企业有一批 REST API，想让智能体调用，但不想为每个接口手写 MCP 服务器。解法：用 api-gateway-mcp-server 技能，指导智能体给 OpenAPI 规范加上 x-google-api-management.mcp 与 x-google-mcp-tool 标注，再由 API Gateway 把 MCP JSON-RPC 请求（initialize、tools/list、tools/call）翻译成对后端的普通 HTTP 请求，同时沿用既有的认证与配额策略。集成步骤：在智能体对话中描述「把这份 OpenAPI 3.x 规范暴露成 MCP 服务器」，技能会引导完成标注、tools/list 的 JWT/API Key 保护与错误排查。收益：复用既有 API 治理体系，无需新建鉴权层。边界：该能力标注为 Public Preview；不适用于 Apigee X 代理包或出站模型路由。

场景四：用技能目录做团队级「能力标准化」

痛点：团队里每个人给智能体的提示词都不一样，同一个「部署到 Cloud Run」的任务，十个人有十种做法。解法：把 google/skills 作为基线技能集，团队再按官方格式补充自有技能，用同一套 CI 与评测流程管理。集成步骤：以 agent-platform-skill-registry 技能为例，它教智能体如何向 Gemini Enterprise Agent Platform 的技能注册中心上传、检索、更新与删除技能，并监控长时操作（LRO）状态。团队可以照搬这套「注册—检索—版本管理」的模式来治理内部技能库。收益：口径统一、可版本化、可评测。边界：技能注册中心与 Agent Platform 绑定；自建技能需自行承担评测成本。

场景五：让智能体在 GKE 上排查 AI 工作负载问题

痛点：TPU 多切片挂起、性能退化、预留容量被泄漏的节点池占用——这些故障的排查知识散落在少数 SRE 脑子里。解法：仓库里有一组专门的 GKE AI 排障技能，例如用 MXLA Hang Analyzer 排查 TPU 多切片挂起、用 ML Diagnostics 监控排查 TPU 性能退化、排查 TPU 预留因节点池容量泄漏导致的库存不足。集成步骤：安装对应的 gke-ai-troubleshooting-* 技能后，把故障现象直接描述给智能体，它会按技能里的排查路径逐项验证。收益：把稀缺的排障经验变成可复用的流程。边界：技能给的是排查路径而非银弹，仍需实际访问集群与日志。

六、快速上手

# 方式一：通用技能市场（推荐）
npx skills add google/skills
npx skills update

# 方式二：按智能体插件市场安装
claude plugin marketplace add google/skills
claude plugin install google-cloud-developer@google-plugins

# Codex
codex plugin marketplace add google/skills   # 再从 /plugins 浏览安装

# Antigravity CLI
agy plugin install https://github.com/google/skills/plugins/cloud/google-cloud-developer

最小验证：安装 finding-google-skills 后，向智能体提问「我要在 Google Cloud 上跑一个需要 GPU 的推理服务，该选什么」，观察它是否抓取 index.json 并把请求路由到 GKE AI/ML Inference 这类技能。

七、横向对比

维度	google/skills	anthropics/skills	mattpocock/skills	纯 MCP 服务器
形态	官方产品技能目录	官方技能示例库	个人工程方法论技能	工具连接协议
覆盖面	Google 全产品线（近 200 技能）	Claude 能力示例	软件工程流程	取决于实现
是否含凭据	否（纯 Markdown）	否	否	是（需认证）
质量机制	CI + 提交评测 + 每周回归	官方维护	单人维护	视实现
分发	通用市场 + 三家插件市场	Claude 生态	通用市场	各家客户端
主要成本	无（Apache-2.0）	无	无	托管与认证成本

需说明：技能与 MCP 并非竞争关系——官方明确主张「技能负责怎么想、MCP 负责怎么连」，两者互补。

八、局限、风险与社区观察

维护模式：官方主导，但贡献通道开放。 仓库接受 bug 报告与新增技能建议（以 issue 形式），但提交者只有 8 人，且贡献数第一的是 cloud-ix-copybara（507 次提交）——这是 Google 内部到公开仓库的同步机器人，意味着绝大部分内容并非社区 PR，而是内部构建后自动导出。

无 Release、无版本标签。 仓库的 Release 列表为空，版本信息散落在每个 SKILL.md 的 metadata.version 与插件 plugin.json 里。对想「钉住一个稳定版本」的团队，这需要额外工作。

覆盖面与生态锁定。 目录几乎全部围绕 Google Cloud。第三方评论（One 的博客《Google Shipped an Official Agent Skills Catalog》）直言：技能只是指令、不是集成，它不持有凭据、不打开连接，一旦任务离开 Google Cloud 就「撞墙」。这既是它的可移植性来源，也是它的边界。

评测数字不可独立复现。 官方宣称技能带来「可测量的准确率与效率提升」，但内部评测套件在导出时被剥离，社区无法独立验证。文中引用的评测方法论来自官方博客，具体分数应视为厂商自述。

生产可用性。 仓库自 2026-03-31 创建，到 2026-11-06 约七个月、23,334 星，提交活跃（近期每日有提交），Apache-2.0 许可宽松，作为「给智能体补领域知识」的基线资产成熟度较高。但需注意部分技能标注 Public Preview（如 API Gateway MCP 服务器），且技能质量参差不齐——官方自己的治理规则也承认，一份含糊的技能会拉低整体体验。

九、小结与行动建议

google/skills 的价值不在于「又多了几个提示词」，而在于它示范了一套可复制的方法论：把领域知识拆成按需加载的技能单元，用索引做路由，用 MCP 做连接，用 CI 与持续评测守住质量。最值得借鉴的三点是：「先查手册再动手」的强制前置条件、提交即评测加每周回归的双层质量闸门、技能与插件（知识 vs 连接）的清晰分层。行动建议：

正在用编码智能体写云上代码的团队：先装 gcloud 与对应产品技能，观察参数幻觉是否下降；这是投入产出比最高的一步。
想让智能体调用内部 API 的团队：研究 api-gateway-mcp-server 的标注方式，把既有 OpenAPI 规范低成本转成 MCP 工具。
要建立团队技能规范的团队：直接借用官方的目录结构、frontmatter 约定与 CI 检查项，把自有技能纳入同一套流程，而不是各写各的提示词。
评估生态锁定的架构师：明确「技能离开 Google Cloud 就失效」这一边界，把 google/skills 定位为 Google Cloud 场景的专用增强，而非通用能力层。
关注 Agent Skills 范式的研究者：把 google/skills 与 anthropics/skills、mattpocock/skills 并读，对比「官方产品知识」「能力示例」「工程方法论」三种技能组织方式的差异。

资料来源（数据获取日期 2026-11-06）：仓库 README、index.json、SKILL.md 样例与 .claude-plugin/marketplace.json（github.com/google/skills，Apache-2.0）、Google Cloud 博客《Level Up Your Agents: Announcing Google's Official Skills Repository》（2026-04-23）与《Behind the scenes: How we build, test, and scale Google Agent Skills》（2026-08-04）、One 博客《Google Shipped an Official Agent Skills Catalog》、AI Native Landscape 项目页。