前言¶
让 Agent 直接拼 gcloud 子命令、猜 flag，很容易写出语法错误或误删资源；即便命令正确，无限制的 list 输出也会占满上下文。常见做法是让人工复核每一条命令，或改用客户端库与 REST API，但运维与排障场景里 CLI 仍是最直接的入口。
下面介绍 Google 在 google/skills 仓库中维护的 gcloud Skill（metadata 版本 1.0.0，分类 CloudInfrastructureAndServices）。它面向 AI Agent，在规划、生成、描述或执行 gcloud 相关任务时，提供语法校验流程、执行护栏与数据精简规则；官方说明明确：不要在编写 Google Cloud 客户端库代码或原始 REST/gRPC 请求时使用本 Skill。
这是什么¶
gcloud 是一份 Agent Skill 文档（SKILL.md），不是 Cloud SDK 安装包。它规定 Agent 与 Google Cloud SDK（gcloud CLI）交互时的强制步骤与禁止项，目标是减少命令幻觉、避免破坏性自动执行、并控制返回数据量。
维护方与源码路径：https://github.com/google/skills/tree/main/skills/cloud/gcloud。
核心功能¶
叶子级语法校验（强制前置）¶
Skill 要求：Agent 对 gcloud 命令、flag、取值与位置参数的先验知识视为易过时且易幻觉，在提出参数、执行命令或写分步计划之前，必须先对叶子子命令做校验：
gcloud help compute instances create
要点如下：
- 父级 help（例如
gcloud help compute）不能替代叶子命令的校验。 - 制定计划时，Step 1 必须是
gcloud help <leaf_command>，再谈 flag 或执行。 - 禁止用网页搜索或外部文档查 CLI 语法；
gcloud help <leaf_command>是语法方面的唯一权威来源。 - 用户已给出的 flag（含
--project=<project_id>）在中间步骤中必须保留。
生成计划时须使用官方规定的四步结构：
- Step 1：
gcloud help <leaf_command>做语法校验 - Step 2：核对必填/可选 flag，并确认是否支持
--dry-run或--validate-only - Step 3：若支持 dry-run，必须先给出带
--dry-run或--validate-only的调用 - Step 4：提出正式命令；若命中「禁止自主执行」列表，须说明禁止自动执行并明确要求用户授权
两种执行方式¶
Agent 可通过两种方式操作 GCP 资源：
- 直接 CLI：在本地或自动化 shell 中执行
gcloud（安装、认证与配置见 Skill 内references/cli-usage.md）。 - MCP：通过 Cloud CLI remote MCP 服务器的结构化工具
run_gcloud_command（见references/mcp-usage.md）。
数据精简（Mandatory）¶
任何 list 命令都必须带上至少一种缩减手段：--limit、--filter 或 --format。
- 投影：
--format="json(key1, key2, ...)"；进阶语法可查gcloud topic projections、gcloud topic formats。 - 条数上限：
--limit=N。 - 过滤：
--filter在服务端收窄结果；模式匹配优先用:，冒号右侧不要加引号。 - Schema 发现：不确定 JSON 字段路径时，先拉一条样本：
gcloud <GROUP> <RESOURCE> list --limit=1 --format=json
再根据结构构造 --format 或 --filter，避免无约束的大列表灌满上下文。
执行约束¶
- 每次只执行一条
gcloud命令，不链式拼接。 - 不使用命令替换、
管道、重定向，便于人工审阅。 - 所有执行类命令应带
--quiet/-q，避免无 TTY 环境下卡在确认提示。 - 禁止「裸」
list（无--limit、--filter、--format）。
项目与位置作用域¶
- 资源查询与变更命令应显式带上
--project=<PROJECT_ID>，不依赖当前默认配置。 - 需要 region/zone/location 的命令必须显式传参，否则会触发交互式选择，与无交互运行冲突。
- 位置未知时可先发现（并注意配合数据缩减），例如：
gcloud compute regions list --project=<PROJECT_ID>
gcloud compute zones list --project=<PROJECT_ID>
gcloud locations list --project=<PROJECT_ID>
安全护栏与禁止自主执行列表¶
破坏性操作（delete、update、remove 等）必须经用户明确授权；Skill 列出不得自主执行的类别，包括但不限于：
- IAM 策略、角色、绑定变更
- 主动启用 API（须用户批准，避免意外计费）
gcloud * delete、gcloud billing *、gcloud organizations *、gcloud kms *gcloud infra-manager deployments apply
若 help 中支持 --dry-run 或 --validate-only，必须先用于预览变更。长耗时操作在支持时可考虑 --async，并按需轮询 operation 状态。
安装与启用¶
gcloud Skill 随 google/skills 仓库分发。官方安装方式为：
npx skills add google/skills
按提示选择具体 Skill（可只选 gcloud）、目标 Agent 以及安装范围（项目或全局）。环境若无 npx，需先安装 Node.js（含 npm/npx）。更新已安装 Skill：
npx skills update
仓库 README 未单独列出 Cursor、Codex CLI、Claude Code 的差异步骤；统一通过 skills.sh 流程安装。Skill 本体为 Markdown 规则与引用文档，Agent 侧需已安装并认证 Google Cloud SDK，CLI 路径与 MCP 配置见 Skill 目录下 references/。
典型用法¶
不熟悉服务时的发现流程¶
- 对目标叶子命令执行
gcloud help <leaf_command>。 - 若不知命令名，从
gcloud help或gcloud help <group>遍历命令树。 - 用
--limit=1 --format=json做 schema 发现。 - 后续 list/query 一律带数据缩减 flag。
计划模板示例（逻辑顺序）¶
以创建 Compute Engine 实例为例，Agent 应先校验语法，再谈参数与 dry-run（具体 flag 以 help 为准）：
gcloud help compute instances create
确认支持 dry-run 后，再提出带 --dry-run 与 --quiet、--project、区域/zone 等用户指定参数的预览命令，最后才进入 Step 4 的正式提案或执行（且不在 denylist 上）。
速查表（来自官方 Skill）¶
| 任务 | 命令模板 |
|---|---|
| 发现 Schema | gcloud <GROUP> <RESOURCE> list --limit=1 --format=json |
| 过滤列表 | gcloud <GROUP> <RESOURCE> list --filter="status:RUNNING" |
| 指定列 | gcloud <GROUP> <RESOURCE> list --format="json(name, id)" |
| 学习 filter 语法 | gcloud topic filters |
自动化脚本方面，Skill 指向 gcloud CLI Scripting Guide。
适用场景与注意¶
适合：由 Agent 规划或执行 GCP 运维、排障、资源查询；需要统一「先 help、再 dry-run、再执行」流程的团队；通过 MCP run_gcloud_command 做结构化调用的环境。
不适合：编写 Cloud 客户端库、直接拼 REST/gRPC（应使用对应开发 Skill 或文档）。
注意：规则偏严（单命令、无管道、禁止用搜索补语法），是为了可审阅与安全；denylist 上的操作即使用户意图明确，Skill 仍要求显式授权。列表与发现命令务必带 --project 与数据缩减，否则易错项目或撑爆上下文。
结尾¶
gcloud Skill 把「叶子 help 校验、四步计划、数据缩减、项目/位置显式作用域、denylist 与 dry-run」写成 Agent 可遵循的同一套规范，适合作为让 Agent 安全调用 GCP CLI 时的官方一手约束来源。源码与完整规则见：https://github.com/google/skills/tree/main/skills/cloud/gcloud。
