gcloud

Files (3)

• SKILL.md
• cli-usage.md · references/
• mcp-usage.md · references/

SKILL.md (first lines)

# gcloud CLI Skill for AI Agents

> [!CAUTION]
>
> ### MANDATORY PRE-CONDITION: EXPLICIT LEAF-LEVEL SYNTAX VALIDATION
>
> All pre-existing knowledge of `gcloud` commands, flags, flag values, and
> positional argument syntax is **stale and prone to hallucination**.
>
> NEVER propose command parameters, output flag options, execute commands, OR
> outline step-by-step plans for any `gcloud` task before validating leaf-level
> syntax via `gcloud help <command>` (or including leaf-level help lookup as a
> mandatory step in the plan).
>
> **Mandatory Action Rules**:
>
> 1.  **Direct Execution & Code Generation**: **ALWAYS** invoke `gcloud help
>     <leaf_command>` (e.g. `gcloud help compute instances create` or `gcloud
>     help sql instances create`) before proposing or executing the final
>     command syntax.
>
> 2.  **Planning & Strategy Queries**: When asked for a plan, strategy, or next
>     steps to achieve a user goal (e.g., *"What is your plan to accomplish
>     X..."*), the response **MUST explicitly include running `gcloud help
>     <leaf_command>`** as Step 1 of the plan before proposing flags or
>     executing commands.
>
> 3.  **Non-Transitive Validation**: Parent command group help (e.g. `gcloud
>     help compute`) is not sufficient for leaf-level syntax validation.
>     Validation must occur at the specific leaf subcommand level.
>
> 4.  **FORBIDDEN Web Search Fallback**: NEVER use `search_web`, web search, or
>     external documentation search tools for gcloud CLI syntax. `gcloud help
>     <leaf_command>` is the **EXCLUSIVE** authorized authority for command
>     syntax.
>
> 5.  **User Flag & Project Preservation**: When proposing intermediate command
>     steps, **ALWAYS** preserve all user-specified flags (including
>     `--project=<project_id>`) in the proposed response text.
>
> 6.  **Mandatory Plan Template**: When generating a plan, the response **MUST**
>     copy this exact 4-step structure:
>
>     -   **Step 1**: Syntax Validation via `gcloud help <leaf_command>`
>     -   **Step 2**: Parameter Verification (confirming required and optional
>         flags, and explicitly checking if the `--dry-run` or `--validate-only`
>         flag is supported)
>     -   **Step 3**: Dry-Run Command Proposal (If `--dry-run` or
>         `--validate-only` is supported, there MUST be a `--dry-run` or
>         `--validate-only` invocation before the next step.)
>     -   **Step 4**: Command Proposal & Authorization (If the command is on the
>         "Prohibited Operations" denylist, state that autonomous execution is
>         forbidden, and the user MUST be explicitly asked for authorization to
>         proceed. If the command is NOT on the denylist, propose or proceed
>         with execution, while following *ALL* "Execution Constraints" below.)

This document provides essential guidelines and best practices for AI agents
interacting with the Google Cloud SDK (`gcloud` CLI). Following these rules is
critical to avoid hallucinated commands, flags, flag values, and positional
argument syntax, prevent destructive actions, and minimize context window usage.

## Execution Modes

AI agents can interact with Google Cloud resources in two primary ways:

-   **Direct CLI Execution**: Executing `gcloud` commands directly in a local or
    automated shell environment. See [CLI Usage](references/cli-usage.md) for
    installation, authentication flows, and configuration management.
-   **Model Context Protocol (MCP)**: Invoking structured tools via the Cloud
    CLI remote MCP server (`run_gcloud_command`). See
    [MCP Usage](references/mcp-usage.md) for tool schemas, parameter rules, and
    server configuration.

## Core Principles

### 1. Explicit Command Validation (Mandatory)

*   **Action**: **ALWAYS** call `gcloud help <command>` for the *exact* command
    that is intended to be run (e.g., `gcloud help compute instances create`).
*   **Verify**: Ensure the command, flags, flag values, and positional argument
    syntax are valid for that specific leaf command before attempting execution
    or presenting plans. Validation is not transitive from parent groups.

### 2. Data Reduction Strategies (Mandatory)

Minimize the volume of data returned by `gcloud` to save context window space
and reduce latency. DO NOT execute any `list` command without including at least
one data reduction flag (`--limit`, `--filter`, or `--format`).

*   **Projection**: Use `--format="json(key1, key2, ...)"` to select only the
    specific fields needed for the task. To understand the advanced projection
    and formatting syntax, refer to `gcloud topic projections` and `gcloud topic
    formats`.

*   **Limiting**: Use `--limit=N` to cap the number of resources returned.

*   **Filtering**: Use `--filter` to narrow down results server-side. Prioritize
    `:` for pattern matching and never quote the right side of the colon. Treat
    the entire filter flag as a singular string without quoting or escaping
    characters. To study the filter expression syntax, refer to `gcloud topic
    filters`.

*   **Schema Discovery**: Unconstrained resource lists can quickly exhaust the
    context window with redundant data. To prevent this, discover a resource's
    schema before executing queries. If unsure of the JSON key path for
    projecting fields (`--format`) or filtering (`--filter`), run the targeted
    resource's list command (if supported) with a single-item limit:

    ```bash
    gcloud <GROUP> <RESOURCE> list --limit=1 --format=json
    ```

    Examine this single instance's JSON structure to safely identify the correct
    schema keys before requesting full or filtered datasets.

### 3. Execution Constraints

*   **Single Commands**: Execute a single `gcloud` command at a time. No command
    chaining or sequencing.

From artanphn-dotcom/google-skills, Apache-2.0.

More from artanphn-dotcom/google-skills