前言¶
讓 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。
