Google 官方 Agent Skills 仓库解读：AI Agent 时代，知识正在从「提示词」变成「可安装能力包」
TL;DR
- 场景 ：Google 官方在 GitHub 开源了
google/skills仓库，把面向 Google Cloud、Gemini API、BigQuery、Cloud Run、GKE、认证、网络可观测性、Well-Architected Framework 的工程知识封装成 Agent 可发现、按需加载、版本化管理的能力包。 - 结论 ：
google/skills不是 SDK、不是 MCP Server，也不是普通 prompt 仓库，而是「Agent 时代的可执行 SOP」。它的真正价值是示范了一种把团队经验沉淀为 Agent 可执行资产的新范式。 - 产出 ：解读仓库的四类能力（产品 Skills / Gemini & Agent Platform / Recipe / Well-Architected），拆解
gemini-api、cloud-run-basics、gke-basics、authentication等典型 skill 的写法；给出 7 条可借鉴的写 skill 原则与 1 张错误速查卡。
版本矩阵
| 功能 / 工具 | 状态 | 说明 |
|---|---|---|
google/skills 仓库定位（Agent Skills 集合） |
✅ 已验证 | GitHub 仓库 github.com/google/skil... 2.0 协议；非 SDK、非 MCP Server、非 prompt 仓库 |
安装方式 npx skills add google/skills |
✅ 已验证 | README 官方安装命令；可选择性安装子 skill |
仓库组织 skills/cloud/ 目录 |
✅ 已验证 | 2026-06-11 仓库 68 commits，主分支 main |
Gemini API 统一 Gen AI SDK（Python google-genai） |
✅ 已验证 | gemini-api skill 明确推荐的当前 SDK |
Gemini API 统一 Gen AI SDK（JS/TS @google/genai） |
✅ 已验证 | gemini-api skill 明确推荐 |
Gemini API 统一 Gen AI SDK（Go google.golang.org/genai） |
✅ 已验证 | gemini-api skill 明确推荐 |
Gemini API 统一 Gen AI SDK（Java com.google.genai:google-genai） |
✅ 已验证 | gemini-api skill 明确推荐 |
Gemini API 统一 Gen AI SDK（C# Google.GenAI） |
✅ 已验证 | gemini-api skill 明确推荐 |
| Cloud Run 资源类型（Services / Jobs / Worker pools） | ✅ 已验证 | cloud-run-basics skill 中分别说明适用场景 |
Cloud Run 硬规则（监听 0.0.0.0、使用 $PORT） |
✅ 已验证 | cloud-run-basics skill 中标注的部署前置条件 |
| GKE skill 主文件路由 + references 拆分 | ✅ 已验证 | gke-basics skill 采用「主 SKILL.md 判定任务 + 按需加载 networking/security/scaling 等 reference」结构 |
| 认证 skill 场景判断（本地 / CLI / 生产） | ✅ 已验证 | authentication skill 强制 Agent 先判断运行位置再选择 ADC / Workload Identity / 凭据模拟 |
| Well-Architected Framework 六大支柱 skill | ✅ 已验证 | 安全、可靠性、成本优化、性能、运营卓越、可持续性 |
| Recipe 类 skill（认证、Onboarding、网络可观测性） | ✅ 已验证 | 跨产品流程型 skill，不绑定单一云产品 |
| Apache 2.0 开源协议、可 fork / remix | ✅ 已验证 | README License 字段明确 |
| 仓库状态：active development | ✅ 已验证 | README 注明目录、安装方式、skill 内容、兼容工具均可能持续变化 |
| 外部 PR / 代码贡献通道 | ✅ 已验证 | CONTRIBUTING.md 表明 Google 当前不接受外部代码贡献，可提 issue / feature request / fork |
| Skill 内置脚本/凭据访问的供应链风险 | ⚠️ 待验证 | 第三方 skill 需要逐个审查来源与权限范围 |
| Skill 内容与最新产品文档同步 | ⚠️ 待验证 | skill 仍可能滞后于官方文档，高变化 API 需配合 MCP / 官方文档核验 |
文章正文
摘要：Google 开源的
google/skills不是 SDK、不是 MCP Server，也不是普通 prompt 仓库，而是一组面向 Google Cloud、Gemini API、BigQuery、Cloud Run、GKE、认证、网络可观测性和 Well-Architected Framework 的 Agent Skills。它的核心意义是：把工程知识沉淀为 Agent 可以发现、按需加载、版本化管理的能力包。对开发者来说，这个仓库不只适合使用 Google 技术栈时减少 AI 幻觉，也提供了一套「如何把团队经验写成 Agent 可执行资产」的参考。
TL;DR：google/skills 到底是什么？
一句话说：google/skills 是 Google 官方维护的 Agent Skills 集合，用来让 AI Agent 在处理 Google 产品和技术任务时，按需加载更准确的工程知识和操作流程。
它不是传统 SDK，不提供一组运行时代码 API。
它不是 MCP Server，不负责实时连接外部工具或数据源。
它也不是普通 prompt 仓库，不是让用户复制一大段提示词再丢给模型。
它更像「工程知识包」：一个 skill 通常是一个目录，核心文件是 SKILL.md，里面写清楚这个 skill 是什么、什么时候用、该怎么做、哪些做法不要用、需要参考哪些资料。复杂 skill 还可以带 references/、scripts/、assets/ 等资源。
这个项目背后的趋势很清楚：AI Agent 的能力边界，正在从「模型本身有多强」，转向「模型能不能在正确时间加载正确知识，并按照正确流程行动」。
Agent Skills：提示词之后的新抽象
Agent Skills 是一种面向 Agent 的开放格式。一个典型目录大概长这样：
text
my-skill/
SKILL.md
references/
scripts/
assets/其中最关键的是 SKILL.md。它通常包含 YAML frontmatter，比如 name 和 description，以及具体的操作说明。
description 很重要，因为它告诉 Agent：这个技能做什么，什么时候应该使用。Agent 启动时不一定读取所有 skill 全文，而是先看到名称和描述；当用户任务命中某个 skill 时，再加载完整说明，必要时继续读取 references、scripts 或 assets。
这叫渐进式披露，也就是按需加载。
这解决了一个非常现实的问题：上下文窗口再大，也不适合无限塞文档。把一个云产品的官方文档、最佳实践、CLI 命令、权限说明、安全注意事项全部塞进上下文，不仅浪费 token，也会让模型注意力分散。
Skill 的思路是：把稳定、重复、容易踩坑、适合任务执行的知识压缩成可索引、可安装、可版本管理的模块。
普通提示词偏「表达」，Skill 偏「能力」。
普通提示词依赖复制粘贴，Skill 可以安装到用户级、工作区级或全局目录。
普通提示词很难审查和复用，Skill 可以放进 Git，走 review、diff、回滚和版本管理。
这就是它真正值得关注的地方。
为什么 Google 要做 google/skills？
因为现代软件工程变化太快，而模型知识天然有截止日期。
SDK 会升级，API 会变，产品命名会变，权限模型会变，安全建议会变，部署命令也会变。模型越擅长写代码，过时知识带来的风险就越大：它可能生成看起来合理、实际上已经不推荐或不能运行的代码。
以 Gemini API 为例，Google 的 skill 明确推荐使用统一的 Gen AI SDK：
- Python：
google-genai - JavaScript / TypeScript：
@google/genai - Go：
google.golang.org/genai - Java：
com.google.genai:google-genai - C#：
Google.GenAI
同时它会提醒不要继续使用旧 SDK，例如 google-generativeai、@google-cloud/vertexai、google-cloud-aiplatform 等旧路径。
这类信息对 AI 编程非常关键。用户问「帮我写一个 Gemini API demo」，模型如果凭旧记忆写旧 SDK，代码可能直接跑不起来。
再看 Cloud Run。部署不是只知道「Cloud Run 可以跑容器」就够了。真正部署时，Agent 要知道服务应该监听 0.0.0.0，端口应该使用环境变量 $PORT；要知道 Cloud Run 有 Services、Jobs、Worker pools；要知道 API、IAM、构建、日志排查和启动失败可能的原因。
这些都是工程经验，不是单纯语言知识。
google/skills 的价值，就是把这些容易过期、容易忘、容易误用的工程知识，整理成 Agent 可以按需加载的技能单元。
google/skills 的项目结构
从当前仓库看，google/skills 的核心内容集中在 skills/cloud/，覆盖 Google Cloud 和 Google AI Agent 相关场景。
它大致可以分成四类。
第一类是具体产品技能，例如 BigQuery、Cloud Run、Cloud SQL、Firebase、GKE、AlloyDB。这类 skill 面向具体产品使用，帮助 Agent 启用 API、创建资源、运行命令、引用文档和规避常见错误。
第二类是 Gemini 与 Agent Platform 技能，例如 Gemini API、Gemini Interactions API、Agent Platform 部署、推理、RAG、Prompt 管理、模型注册、调优、Skill Registry 等。这类 skill 更接近 Google 自己的 AI Agent 平台栈。
第三类是 recipe 技能，例如认证、Onboarding、网络可观测性。它们不绑定单一产品，而是绑定跨产品流程。
第四类是 Well-Architected Framework 技能，例如安全、可靠性、成本优化、性能优化、运营卓越和可持续性。它们让 Agent 不只是执行命令，也能参与架构审查。
这说明 google/skills 不是零散 prompt 集合，而是围绕 Google Cloud 工程任务做系统拆分。
典型 skill：Gemini API
gemini-api 是最值得关注的 skill 之一。
它的目标不是简单介绍 Gemini API 能做什么，而是让 Agent 走当前推荐的 SDK 和工程路径。它会强调 Gen AI SDK，也会标注旧 SDK 和旧命名的风险。
这背后有一个关键问题：AI 编程最容易错在「写法看起来熟，但版本已经旧」。
如果没有 skill，模型可能从训练语料里抽到旧包名、旧初始化方式、旧示例。用户复制后发现依赖装不上、方法不存在、认证方式不对。
Gemini API skill 的作用，是把 Agent 拉回当前推荐路径。
这说明 Skill 不只是知识补充，而是在设置工程边界：应该用什么，不应该用什么，遇到不确定信息查哪里，哪些概念可能已经改名。
典型 skill：Cloud Run
Cloud Run skill 展示了部署类任务为什么需要 skill。
部署类任务最怕「看起来会，实际少关键细节」。一个 Agent 如果只知道 Cloud Run 是 serverless container 平台，可能能写介绍，却未必能正确部署。
Cloud Run skill 会把资源类型拆清楚：
- Services：响应 HTTP 请求，适合无状态服务。
- Jobs：运行到完成，适合批处理、定时或手动任务。
- Worker pools：常驻后台工作负载，适合 Kafka consumer、Pub/Sub pull queue、RabbitMQ consumer 等拉取型任务。
它还会强调部署前置条件、IAM 权限、gcloud run deploy、gcloud run jobs create、gcloud run worker-pools deploy 等命令路径。
更有价值的是硬规则：容器必须监听 0.0.0.0，并使用 Cloud Run 注入的 $PORT。很多本地服务监听 127.0.0.1:8080，本地没问题，上 Cloud Run 就启动失败。
这就是 skill 最适合沉淀的东西：小但致命的工程经验。
典型 skill：GKE 与认证
GKE skill 体现了另一种成熟写法：主文件做路由，复杂内容拆到 references。
GKE 涉及 Kubernetes、Autopilot、Standard、网络、安全、Workload Identity、RBAC、扩缩容、GPU/TPU 推理、多租户、备份、Terraform、升级和生产审计。如果把所有内容塞进一个 SKILL.md，会非常臃肿。
更合理的方式是：主 SKILL.md 判断任务类型，然后按需加载 networking、security、scaling、observability、cost、terraform、production readiness 等 reference。
这对我们自己写团队 skills 很有启发：主文件不应该变成大百科，而应该成为任务路由入口。
认证 skill 也很典型。很多 Agent 一遇到云认证，就会建议下载 service account key。这个方案能跑，但不一定安全，也不一定推荐。
Google Cloud 认证问题要先判断：谁在认证？代码运行在哪里？目标是什么？是本地开发、CLI 管理，还是生产服务？是否可以使用 Application Default Credentials、Workload Identity、metadata server、service account impersonation 或 workload identity federation？
这类 skill 的价值不是直接给一个命令，而是让 Agent 先做场景判断，避免给出能跑但不安全的答案。
Agent Skills 和 MCP 的关系
很多人看到 Agent Skills，会想到 MCP。
两者并不冲突。
MCP 更像工具和上下文协议，擅长连接外部工具、数据源、文档检索、API、数据库、文件系统。
Skill 更像任务知识包，擅长提供压缩后的领域知识、操作流程、最佳实践、边界条件和任务分流规则。
可以这样理解：
- MCP 负责「查」。
- Skill 负责「会」。
- MCP 负责连接外部世界。
- Skill 负责告诉 Agent 应该怎样使用这些连接。
只靠模型，知识会过期。
只靠 MCP，检索会膨胀。
只靠 prompt，维护会混乱。
Skill + MCP + Agent runtime，才更接近可持续工程方案。
对开发者和团队的意义
google/skills 对普通开发者的重要性，不只在于你是否使用 Google Cloud，而在于它展示了一种新的知识组织方式。
过去我们沉淀经验，通常写博客、文档、wiki、脚本、模板、SOP、README。人可以读，但 Agent 不一定能高效使用。Agent 需要更明确的触发条件、更短的上下文、更直接的步骤、更清晰的边界、更少歧义的命令。
Skill 本质上就是面向 Agent 的 SOP。
个人开发者可以给自己的工作流写 skill，例如博客写作、服务器巡检、SEO 发布、Java 后端开发、Kubernetes 排障。
团队则可以把开发流程、数据库变更、接口兼容性检查、日志排查、发布前检查、安全审查、性能压测、故障复盘写成 workspace skills，并放进 Git 做 review。
这会形成一种新的工程资产：AI 可执行的团队知识库。
google/skills 的局限和风险
第一，它仍在活跃开发中。仓库 README 明确提示 active development，目录、安装方式、技能内容和兼容工具都可能继续变化。
第二，外部贡献受限。贡献文档显示，Google 当前不接受外部 PR 或代码贡献。用户可以提 issue、报告不准确内容、请求新 skill，也可以 fork/remix，但主仓库不是开放共建模式。
第三，它主要覆盖 Google 技术栈。如果你主要使用 AWS、Azure、阿里云、自建 Kubernetes，它不能直接覆盖全部需求，但仍然可以作为写 skill 的参考模板。
第四，Skill 不是实时文档。它仍然可能过期，所以高变化 API 最好结合 MCP、官方文档和当前仓库内容核验。
第五，Skill 也是供应链依赖。它会影响 Agent 行为，甚至可能包含脚本、模板和工具权限。第三方 skill 不能像普通提示词一样随便安装，尤其是包含可执行脚本或凭据访问的 skill，需要审查来源和内容。
如何从 google/skills 学会写自己的 skill？
可以借鉴几条原则。
第一，description 要写清楚触发条件。Agent 能否正确使用 skill，很大程度取决于描述是否准确。
第二，主文件不要过度膨胀。复杂领域要拆 references，让主 SKILL.md 负责识别任务和分流。
第三，要写硬规则。例如 Cloud Run 必须监听 0.0.0.0 和 $PORT，这类规则最能减少失败。
第四，要写反模式。比如不要使用旧 SDK，不要轻易下载长期 service account key。
第五，要写排查路径。权限错误看哪里，启动失败看哪里，日志怎么查，依赖错误怎么处理。
第六，要引用权威资料入口。Skill 不是替代官方文档，而是告诉 Agent 何时查、去哪查、怎么查。
第七，高风险任务要写「先澄清什么」。比如认证、生产部署、安全变更、数据删除，都不应该让 Agent 直接行动。
最终判断
google/skills 表面上只是一个 Markdown 仓库，但它背后指向的是 AI Agent 工程化的核心问题：
模型不可能内置所有最新、正确、细粒度的工程知识；文档又太长、太散，不适合直接塞进上下文；实时检索有成本和噪声；临时 prompt 难以维护和审查。
于是需要一种中间层，把专业知识压缩成 Agent 可发现、可加载、可执行、可版本管理的能力包。
Agent Skills 就是这个中间层。
Google 做 google/skills，不是为了再造文档站，而是为了让 Agent 更可靠地使用 Google 技术栈。
它真正传递的信号是：AI 编程不会只比谁的模型更强，还会比谁的技能库更高质量，谁的工作流更结构化，谁能把团队知识沉淀成 Agent 可执行资产。
从这个角度看，google/skills 不只是一个项目，而是一种新范式的样板：AI Agent 时代，真正稀缺的不是提示词，而是可维护、可验证、可迁移的工程知识。
参考来源
- Google Skills GitHub 仓库：github.com/google/skil...
- Gemini API skill：github.com/google/skil...
- Cloud Run skill：github.com/google/skil...
- BigQuery skill：github.com/google/skil...
- Google Skills 贡献说明：github.com/google/skil...
作者：武子康的个人博客