Agent-Skills.md

Agent Skills: Using gcloud Safely with safe-gcloud

This skill should be used when the user asks to "run a gcloud command", "use gcloud", "access Google Cloud", "list GCP projects", "check gcloud config", or any task involving the Google Cloud CLI. Also use when Claude needs to suggest patterns for the gcloud allowlist or explain why a gcloud command was blocked. Use this skill immediately when you see "Direct gcloud commands are blocked" or "Use the safe-gcloud wrapper instead" in an error message.

UncategorizedID: dhughes/claude-marketplace/safe-gcloud-usage

Repository

dhughes/claude-marketplace
dhughesLicense: MIT
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/dhughes/claude-marketplace/tree/HEAD/plugins/safe-gcloud/skills/safe-gcloud-usage

Skill Files

Browse the full folder contents for safe-gcloud-usage.

Download Skill

Loading file tree…

plugins/safe-gcloud/skills/safe-gcloud-usage/SKILL.md

Skill Metadata

Name
safe-gcloud-usage
Description
This skill should be used when the user asks to "run a gcloud command", "use gcloud", "access Google Cloud", "list GCP projects", "check gcloud config", or any task involving the Google Cloud CLI. Also use when Claude needs to suggest patterns for the gcloud allowlist or explain why a gcloud command was blocked. Use this skill immediately when you see "Direct gcloud commands are blocked" or "Use the safe-gcloud wrapper instead" in an error message.

Using gcloud Safely with safe-gcloud

Overview

Direct gcloud commands are blocked in this environment. All Google Cloud CLI operations must go through the safe-gcloud wrapper script, which enforces a project-specific allowlist of permitted commands.

How to Run gcloud Commands

Execute gcloud commands through the safe-gcloud wrapper script:

bash ${CLAUDE_PLUGIN_ROOT}/skills/safe-gcloud-usage/scripts/safe-gcloud.sh <command> [args...]

Examples:

bash ${CLAUDE_PLUGIN_ROOT}/skills/safe-gcloud-usage/scripts/safe-gcloud.sh projects list --format=json
bash ${CLAUDE_PLUGIN_ROOT}/skills/safe-gcloud-usage/scripts/safe-gcloud.sh config get-value project
bash ${CLAUDE_PLUGIN_ROOT}/skills/safe-gcloud-usage/scripts/safe-gcloud.sh auth list

The wrapper passes all arguments, flags, and piped input directly to gcloud for permitted commands.

Allowlist Configuration

Each project defines permitted commands in .claude/gcloud-allowlist.json. This file contains a JSON array of command patterns.

Pattern Syntax

| Pattern | Matches | Does Not Match | |---------|---------|----------------| | projects list | Exactly gcloud projects list | gcloud projects list --format=json | | projects list:* | gcloud projects list with any args/flags | gcloud projects describe | | projects:* | Any gcloud projects subcommand | gcloud compute instances list |

Example Allowlist

[
  "projects list:*",
  "config get-value:*",
  "auth list",
  "compute instances list:*",
  "compute instances describe:*"
]

Critical Restrictions

NEVER attempt to edit .claude/gcloud-allowlist.json. This file is under user control only. When a command is blocked due to missing permissions:

  1. Inform the user which command was blocked
  2. Suggest the pattern they could add to permit it
  3. Wait for the user to update the allowlist themselves

When Commands Are Blocked

If safe-gcloud blocks a command, it provides:

  • The exact command that was attempted
  • An error explaining the command is not in the allowlist
  • A suggested pattern to add

Example blocked output:

ERROR: Command not permitted by allowlist.

Attempted command: gcloud compute instances list --zone=us-central1-a

The allowlist at .claude/gcloud-allowlist.json does not include a pattern that permits this command.

To allow this command, add an appropriate pattern to the allowlist.
For example, to allow this specific command with any flags:
  "compute instances list:*"

Suggesting Patterns to Users

When the user asks what pattern to add, analyze the command and suggest the appropriate pattern:

  • For a specific command with flags: "<command> <subcommand>:*"
  • For all subcommands of a service: "<service>:*"
  • For exact command only (no flags): "<command> <subcommand>"

Example suggestions:

  • User wants gcloud run deploy: suggest "run deploy:*"
  • User wants all compute commands: suggest "compute:*"
  • User wants only gcloud auth list with no flags: suggest "auth list"

Missing Allowlist File

If .claude/gcloud-allowlist.json does not exist, all gcloud commands are blocked. Inform the user they need to create this file with their desired patterns.

Dependencies

The safe-gcloud wrapper requires:

  • gcloud CLI installed and configured