gcloud CLI Skill for AI Agentsgoogle-cloud-developer 插件中面向 GCP 操作的安全验证、数据缩减与护栏实践【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本文基于google-cloud-developer插件中的 gcloud 技能文档SKILL.md展开系统讲解该技能为 AI Agent 执行gcloud命令所设计的完整规则体系从叶子级语法验证这一强制前置条件到数据缩减策略、执行约束、项目/位置作用域控制再到破坏性操作的 Denylist 与结构化发现工作流。读完后你能够理解如何让 Agent 在面对 GCP 命令时不产生幻觉参数、不触发交互挂起、不越权执行危险操作并能复用到任何LLM 驱动 CLI的场景中。1. 技能定位与触发边界该技能定义于 SKILL.md其 frontmatter 元数据明确了适用范围category: CloudInfrastructureAndServices应当使用的场景规划、生成、构造、描述或执行任何gcloudCLI 命令时包括回答gcloud语法问题、格式化 flag 等不应使用的场景编写 Google Cloud 客户端库代码client library或裸 REST/gRPC API 请求。从插件维度看plugin.json 显示该插件版本为 1.1.1官方描述为Google Cloud guidance for coding agents: first-project onboarding, authentication and credential selection, and safety-critical validation for gcloud CLI commands。gcloud 技能正是其中安全关键验证safety-critical validation这一职责的核心承载。2. 设计动机模型先验知识在 gcloud 上是过期且易幻觉的文档开篇以一个 CAUTION 级别的强制前置条件MANDATORY PRE-CONDITION定调所有关于gcloud命令、flag、flag 取值以及位置参数语法的既有知识都是过期的、容易产生幻觉的。在任何gcloud任务中绝不能在通过gcloud help command完成叶子级语法验证之前就提出命令参数、输出 flag 选项、执行命令或勾勒分步计划。这条规则针对的是 LLM 的典型失效模式模型记忆中的 flag 可能已被上游 CLI 版本重命名、移除或位置参数顺序已变化。因此该技能把先验证、后提议/执行升级为不可跳过的流程约束。其Mandatory Action Rules共五条直接执行与代码生成在提议或执行最终命令语法之前必须调用gcloud help leaf_command例如gcloud help compute instances create或gcloud help sql instances create。规划与策略类查询当用户询问完成 X 的计划/策略/下一步时响应必须把执行gcloud help leaf_command显式列为计划的 Step 1之后才能提出 flag 或执行命令。验证不可传递Non-Transitive Validation父命令组的 help如gcloud help compute不足以完成叶子级语法验证验证必须发生在具体的叶子子命令层级。禁止 Web 搜索兜底绝不允许使用search_web、网页搜索或外部文档搜索工具获取gcloud命令语法gcloud help leaf_command是命令语法的唯一授权权威来源。用户 flag 与项目保留提议中间步骤时必须保留用户已指定的全部 flag包括--projectproject_id在响应文本中。此外文档给出了一个强制计划模板Mandatory Plan Template生成计划时必须复制这个精确的 4 步结构Step 1通过gcloud help leaf_command做语法验证Step 2参数核对确认必选/可选 flag并明确检查是否支持--dry-run或--validate-onlyflagStep 3Dry-Run 命令提议若支持--dry-run或--validate-only下一步之前必须先有一次该 flag 的调用Step 4命令提议与授权若命令在Prohibited Operations Denylist 上须声明禁止自主执行并向用户显式征求授权否则提议或直接执行同时遵循下文全部Execution Constraints。这套验证 → 核对 → 预演 → 授权/执行的管线是整篇文档最核心的流程骨架后文的每条原则都是对它的展开。3. 两种执行模式直接 CLI 与远程 MCP文档指出 Agent 与 Google Cloud 资源交互有两种主要方式并分别指向两个参考文档直接 CLI 执行Direct CLI Execution在本地或自动化 shell 环境中直接执行gcloud命令安装、认证流与配置管理详见 cli-usage.mdModel Context ProtocolMCP通过 Cloud CLI 远程 MCP 服务器的结构化工具run_gcloud_command调用工具 schema、参数规则与服务器配置详见 mcp-usage.md。第 10 节会对这两条路径的关键细节做综述此处先聚焦主文档的规则本身。4. 核心原则一显式命令验证强制这一条在正文中再次强调动作对将要执行的确切命令例如gcloud help compute instances create总是调用gcloud help command核对内容在执行或呈现计划之前确认命令、flag、flag 取值与位置参数语法对该特定叶子命令有效验证不能从父命令组传递。与第 2 节的差异在于措辞从提议前扩展到呈现计划前并且明确了验证对象是leaf command叶子命令而非命令树节点——这与规则 3Non-Transitive Validation相互呼应共同杜绝查了gcloud help compute就以为知道create的参数这类捷径。5. 核心原则二数据缩减策略强制gcloud的默认输出表格全列、无过滤的资源列表会迅速消耗 Agent 的上下文窗口并增加延迟。文档给出四条强制策略总纲是没有至少一个数据缩减 flag--limit、--filter或--format不得执行任何list命令。5.1 投影Projection用--formatjson(key1, key2, ...)只选取任务所需的具体字段。进阶的投影与格式化语法参考gcloud topic projections和gcloud topic formats。5.2 限制Limiting用--limitN封顶返回资源数量。5.3 过滤Filtering用--filter在服务端缩小结果集。文档特别强调了两条易错细节优先使用:做模式匹配且冒号右侧永远不要加引号把整个 filter flag 当作单一字符串处理内部字符不加引号、不做转义。表达式语法学习入口是gcloud topic filters。5.4 Schema 发现Schema Discovery无约束的资源列表会因冗余数据快速耗尽上下文窗口。正确做法是先发现 schema 再构造查询不确定要投影--format或过滤--filter的 JSON key 路径时先以单条限制执行目标资源的 list 命令gcloud GROUP RESOURCE list --limit1 --formatjson检查这单个实例的 JSON 结构确认正确的 schema key 之后再请求全量或过滤后的数据集。这是用小样本建立数据结构认知、避免盲目大查询的典型模式。6. 核心原则三执行约束6.1 单命令执行一次只执行一条gcloud命令禁止命令链chaining或顺序编排sequencing。6.2 禁止 Shell 操作符不得使用命令替换$(...)、管道|或重定向、、。目的是提高命令安全性并让命令对用户更容易理解和审查——这与 6.1 共同保证用户看到的命令 实际执行的命令。6.3 非交互执行--quiet/-q所有执行类命令都应携带--quiet或-q全局 flag文档给出的示例gcloud pubsub topics delete temp-topic --quiet --projecttest-project其原理值得单独展开AI Agent 运行在无 TTY、无 stdin 处理器的 headless 非交互环境中。若命令需要用户确认删除资源、批准默认值、选择未指定的 region 等不带--quiet时gcloud会无限期挂起等待输入导致后台任务超时。加上--quiet后gcloud强制进入非交互模式——要么自动接受安全的默认选择要么在缺少必要参数时立即显式报错两种结果对 Agent 都是可处理的。6.4 禁止无约束 List再次重申No Blind Lists没有--limit、--filter或--format的list命令绝不允许执行。7. 核心原则四项目与位置作用域关键为使命令确定、非交互、且命中正确环境必须显式提供项目与位置作用域7.1 显式项目目标不依赖激活配置active configuration的默认值。除纯本地配置命令外所有资源操作与查询命令都必须追加--projectPROJECT_ID避免误操作到错误项目。7.2 防止位置提示Location Prompts许多 GCP 资源是区域级regional或可用区级zonal。若省略位置 flag--region、--zone、--locationgcloud会触发交互式选择提示——这直接违反无交互规则。因此命令需要位置时必须显式提供。7.3 位置发现不知道该服务的 region/zone/location 时先执行发现命令结果多时记得加限制Compute EngineVM、网络gcloud compute regions list --projectPROJECT_ID gcloud compute zones list --projectPROJECT_ID其他服务标准 API 风格许多 GCP 服务使用统一的locations list命令gcloud GROUP locations list --projectPROJECT_ID例如gcloud artifacts locations list、gcloud kms locations list、gcloud secrets locations list。8. 安全护栏与 Prohibited OperationsDenylist文档以 CAUTION 框声明总原则破坏性动作delete、update、remove必须经用户显式授权除非处于安全的、预批准的工作流中被明确指示否则绝不自主调用。在此之上以下操作被明确列入 Denylist——永远不得自主执行需要人工在环human-in-the-loop授权操作分类风险说明任何 IAM 策略、角色、binding 的修改安全权限提升、管理锁定、服务中断或未授权数据暴露主动启用 APINo Proactive API Enabling财务假设所需 API 已启用防止意外的资源开通与账单启用任何 API 都必须经用户批准gcloud * delete破坏性不可逆的资源销毁如项目删除或数据清空gcloud billing *财务服务中断或无上限成本风险gcloud organizations *治理组织级变更影响所有用户的安全态势gcloud kms *加密数据被永久锁死的风险gcloud infra-manager deployments apply破坏性自主 IaC 执行可能销毁受管资源值得注意的是不主动启用 API这一条它把 Denylist 从危险命令扩展到了看似无害但会产生账单的副作用体现了护栏对财务风险的覆盖。9. 执行指南Dry Run、异步与非交互Dry Run强制若命令的 help 输出中列出了--dry-run或--validate-only或等价 flag提议命令或初次执行时必须包含该 flag并总是在实际执行前用 dry run 预演变更。长时运行操作对支持的命令强烈建议对长时操作使用--asyncflag避免阻塞 agentic 流程但并非每个命令都有--async。对返回 operation ID 的命令无论通过--async还是默认行为若下一步依赖其结果必须轮询操作状态直至完成。非交互 flag--quiet在提议或执行的所有命令中包含--quiet或-q保证非交互执行、不等待 TTY 确认。10. 结构化发现工作流Discovery Workflow面对不熟悉的服务时文档规定了一个 4 步工作流调用 Help执行前先对目标叶子命令调用gcloud help COMMAND遍历命令树若不确定确切命令对命令组执行 help如gcloud help compute或gcloud help来发现可用的子组与命令发现 Schema执行gcloud GROUP RESOURCE list --limit1 --formatjson检查 JSON key再构造 filter 或 projection不得执行无作用域 flag如--limit1的无约束 list防止上下文窗口耗尽强制数据缩减所有命令执行都包含数据缩减 flag--limit、--filter、--format。该工作流与第 2 节的 4 步计划模板互为表里模板解决执行前的验证与授权管线本工作流解决陌生服务下的信息获取顺序。11. 快速参考表Cheat Sheet任务命令模板发现 Schemagcloud GROUP RESOURCE list --limit1 --formatjson过滤列表gcloud GROUP RESOURCE list --filterstatus:RUNNING指定列gcloud GROUP RESOURCE list --formatjson(name, id)学习 Filter 语法gcloud topic filters学习 Format 语法gcloud topic formats学习 Projection 语法gcloud topic projections异步操作gcloud COMMAND --async查看操作状态gcloud operations describe OPERATION_ID常用命令速查gcloud cheat-sheet列出 RegionGCEgcloud compute regions list --projectPROJECT_ID列出 ZoneGCEgcloud compute zones list --projectPROJECT_ID列出 Locationsgcloud GROUP locations list --projectPROJECT_ID12. 参考文档一CLI 安装、认证与本地配置cli-usage.md 覆盖直接执行路径所需的平台级前置知识要点如下。安装与组件管理若执行环境未安装gcloud二进制应参考官方 Google Cloud CLI 安装指南进行平台级安装。安装后gcloud components命令组管理可选组件工具、模拟器、语言运行时gcloud components list # 列出可用组件 gcloud components install {component_id} --quiet # 安装组件 gcloud components update --quiet # 更新全部已安装组件注意若gcloud是通过 APT、DNF 等系统包管理器安装的应使用系统包管理器而非gcloud components install来安装组件。认证方式按运行环境选择这是该参考文档最实用的部分场景命令说明用户账户交互式gcloud auth login按浏览器提示登录并授权用户账户无头gcloud auth login --no-browser容器/远程 SSH 等无浏览器环境复制生成的 URL 到另一台机器完成登录把授权码贴回终端ADCgcloud auth application-default login为客户端库与本地应用配置凭据无头环境追加--no-browser服务账号密钥gcloud auth activate-service-account --key-filepath/to/key.json无头自动化安全建议收紧 JSON key 文件权限或优先 Workload Identity / 模拟服务账号模拟推荐用于开发与 Agentgcloud config set auth/impersonate_service_account {service_account_email}用户身份临时假定服务账号身份无需保存长期私钥文件要求目标服务账号上具有roles/iam.serviceAccountTokenCreator角色实现最小权限与可审计访问Workload Identity Federation见官方 Authorizing the gcloud CLI 文档面向 CI/CD 与外部计算环境GitHub Actions、AWS、本地数据中心使用联合令牌、免管理 SA key本地配置管理gcloud config命令组管理本地配置属性、命名 profile 与默认值。命名配置Named Configurations可维护多套隔离属性如 dev / staging / prodgcloud config configurations create {config_name} # 创建配置 gcloud config configurations list # 列出配置 gcloud config configurations activate {config_name} # 激活配置常用属性设置gcloud config set core/project {project_id} # 激活项目 gcloud config set compute/region {region} # 默认计算 region gcloud config set compute/zone {zone} # 默认计算 zone gcloud config list # 查看全部激活属性这里值得与主文档呼应的一点主文档要求 Agent 命令中总是显式携带--project而不依赖core/project默认值——因为命名配置切换是机器状态而显式 flag 是命令自身属性后者才可被用户逐条审查。13. 参考文档二Cloud CLI 远程 MCP 服务器mcp-usage.md 描述第二条执行路径Agent 不跑本地 shell而是通过Cloud CLI 远程 MCP 服务器由 Cloud CLI Execution APIcloudcli.googleapis.com支撑发起结构化工具调用。服务器与工具概览服务器端点https://cloudcli.googleapis.com/mcp传输HTTPJSON-RPC 2.0可用工具run_gcloud_command——在受管的远程环境中替用户安全地执行单条gcloud命令。客户端配置在mcp_config.json中配置服务器条目且authProviderType必须设为google_credentials{ mcpServers: { gcloud-remote: { serverUrl: https://cloudcli.googleapis.com/mcp, authProviderType: google_credentials } } }该字段是强制项它指示 MCP 客户端附带带有https://www.googleapis.com/auth/cloud-platformOAuth 作用域的 ADC省略该字段将导致客户端发送未认证请求返回401 Unauthorized。两个必满足的前置条件API 启用目标项目必须启用 Cloud CLI Execution APIcloudcli.googleapis.com。可通过控制台 API 库页面启用或通过 CLIgcloud services enable cloudcli.googleapis.com --project{project_id}IAM 角色调用者身份须在目标项目上同时持有MCP Tool User角色roles/mcp.toolUser授予mcp.tools.call权限以及底层资源上的标准 IAM 权限例如roles/compute.viewer、roles/run.developer。二者任一缺失端点在工具发现tools/list与工具调用tools/call阶段都会返回403 Forbidden。工具参数run_gcloud_command接受三个参数commandstring必填完整待执行的gcloud命令行字符串例如gcloud compute instances list --project{resource_project} --formatjsonprojectstring必填托管 Cloud CLI Execution API 的项目资源名格式projects/{api_project}input_files对象列表可选执行前需置入远程执行环境的文件每项含相对path与字符串contents。文档特别澄清了一个极易混淆的双项目上下文顶层project参数projects/{api_project}仅用于cloudcli.googleapis.comAPI 本身的配额、计费与 API 启用不设置被执行命令的项目上下文对项目作用域命令必须在command字符串内显式包含--project{resource_project}且该资源项目不必是托管 Cloud CLI Execution API 的项目对非项目作用域命令如 billing、organization 查询若底层 API 需要配额项目必须包含--billing-project{billing_project}。调用示例含 input_files 的gcloud run services replace场景{ command: gcloud run services replace service-config.yaml --regionus-central1 --projectmy-resource-project, project: projects/my-cloudcli-api-project, input_files: [ { path: service-config.yaml, contents: apiVersion: serving.knative.dev/v1\nkind: Service\nmetadata:\n name: my-service\n... } ] }响应结构工具返回exit_code、stdout、stderr、output_files四个字段其中exit_code是命令成败的首要且权威指标exit_code 0当且仅当命令成功信息性 stderrgcloud的stderr在exit_code 0时经常包含状态消息、进度更新与--async操作跟踪 ID——Agent不得仅因stderr非空就判定命令失败错误诊断exit_code ! 0时诊断信息可能出现在stderr或stdout任一流需两者都检查后再形成修正。不支持的命令远程服务器运行在沙箱化、非交互环境中管理本地机器状态或交互能力的命令组不受支持非穷尽列表gcloud auth、gcloud config、gcloud iam service-accounts、gcloud init、gcloud survey、gcloud compute ssh/gcloud app instances ssh。安全与执行指南与主文档一致且互相强化变更类命令create/delete/update/patch不得在无显式用户授权下自主调用长时操作建 VM、GKE 集群、数据库实例在command字符串中追加--async以避免超时command字符串中必须使用--formatjson、--filter、--limit约束输出量可能触发交互确认的命令包含--quiet。14. 插件集成视角技能在 google-cloud-developer 中的位置从 plugin.json 可见gcloud 技能是插件三大职责之一首项目 onboarding、认证与凭据选择、gcloud 命令安全验证。插件还捆绑了一个Developer Knowledge MCP 服务器端点https://developerknowledge.googleapis.com/mcp其接入配置见 mcp.json、mcp_config.json 与 gemini-extension.json——注意后两者同样要求authProviderType为google_credentials与远程 Cloud CLI MCP 的认证模式一致。插件内的 rules/google-cloud-discovery.md 则提供技能目录的路由地图当本插件安装的技能覆盖不到请求所需深度时应指明可能的目录技能名称并提议安装而不是凭名字猜测技能内容——这与 gcloud 技能禁止以先验知识替代gcloud help验证的精神一脉相承先查权威来源再给答案。15. 小结可迁移到LLM 驱动任意 CLI的规则集把这篇技能文档抽象出来它实际上给出了一套通用的 Agent-CLI 交互护栏可迁移到kubectl、az、terraform等场景叶子级 help 是唯一语法权威先验知识视为过期验证不可传递、不可用外部搜索替代输出即上下文成本--limit/--filter/--format三件套强制配合--limit1 --formatjson的 schema 发现法headless 假设--quiet默认携带禁止 shell 操作符与命令链保证命令可逐条审查确定性作用域显式--project/ 位置 flag不依赖机器级默认配置Denylist 显式授权危险域IAM、billing、organizations、kms、delete、IaC apply一律人工在环预演优先help 输出中出现 dry-run 类 flag 就必须先用长时操作用--async加状态轮询。以上规则在仓库中的完整原始文本可直接查阅 SKILL.md、cli-usage.md 与 mcp-usage.md。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考