调查研究-178 Google 官方 Agent Skills 仓库解读：AI Agent 时代，知识正在从「提示词」变成「可安装能力包」

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 开源的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 的开放格式。一个典型目录大概长这样：

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 仓库：https://github.com/google/skills
• Gemini API skill：https://github.com/google/skills/tree/main/skills/cloud/gemini-api
• Cloud Run skill：https://github.com/google/skills/tree/main/skills/cloud/cloud-run-basics
• BigQuery skill：https://github.com/google/skills/tree/main/skills/cloud/bigquery-basics
• Google Skills 贡献说明：https://github.com/google/skills/blob/main/CONTRIBUTING.md

作者：武子康的个人博客