agentleFS
jpantsjohajpantsjoha/googlecloud-plugin/skills/gcloud-guardrails/SKILL.md

gcloud-guardrails

Skill4 starsChanged 4 months agoMITView on GitHub

Command-level safety rules for every gcloud CLI call an agent plans, proposes or runs: validate leaf syntax with gcloud help, dry-run first, reduce output, scope project and location explicitly, run one command at a time, and stop for human authorisation on a fixed denylist (IAM changes, deletes, billing, organizations, KMS, IaC apply, API enablement, CLI installation). Applies alongside every service skill. Does not cover client-library code or raw REST calls. Use this for how a gcloud command is built and executed; use gcp-security instead to review a design's security posture. Use when the user mentions: gcloud command, run gcloud, gcloud syntax, gcloud flags, gcloud dry run, validate gcloud, gcloud safety, destructive gcloud.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every gcloud task, whether executed now or written up as a plan, follows these steps in order.

    line 20
  2. Very specific:

    If a location is unknown, discover it read-only first (for example gcloud run services list --project=PROJECT_ID …

    line 40
  3. Very specific:

    Never run a bare list. To learn a resource's field names before projecting, fetch one record: gcloud <group> <resource> list …

    line 50
  4. Distinctive:

    When unsure which class a command is, treat it as consequential.

    line 61
  5. Distinctive:

    No dry run available — say so.

    line 91

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

gcloud Guardrails

The command-level half of ADR-004. Service skills say what to run; this skill says how any gcloud command is built, checked and executed. It applies whether the command runs in a local shell or through the gcloud MCP server's run_gcloud_command tool.

Remembered gcloud syntax is stale. Commands, flags and flag values change between SDK releases, and a plausible flag that no longer exists is the most common agent failure with this CLI.

The four-step plan

Every gcloud task, whether executed now or written up as a plan, follows these steps in order. A plan that omits step 1 is incomplete.

  1. Validate syntax — run gcloud help <group> <resource> <verb> on the exact leaf command. Help on a parent group (gcloud help compute) does not validate a leaf.
  2. Verify parameters — confirm required flags, the flags the user named, and whether the command supports --dry-run or --validate-only.
  3. Dry run — if either flag is supported, run it before the real command and show the result.
  4. Classify, then propose or execute — see Authorisation below. Read-only commands run under the execution rules. Everything else is proposed with its effect and waits for a named human to authorise it.

gcloud help is the authority for syntax. Do not substitute web search or recall. Use the Developer Knowledge MCP for concepts (which service, which role), not for flag spelling.

Execution rules

RuleWhy
One gcloud command per call. No &&, ;, pipes, redirection or $(...). Through the gcloud MCP server, pass args as an array without the leading gcloud (["run", "services", "list", "--project=PROJECT_ID"]).Each step must be inspectable and its exit code attributable.
Pass --project=PROJECT_ID on every project-scoped command, using the project settled by gcp-project-context. Never rely on the active configuration. Commands that act on no session project need none: help and --help, config, auth, components, info, init, meta, topic, version; and projects, organizations and billing, which name their target explicitly (a project ID, organization or billing account) rather than using a session project. Changes to billing and organizations remain on the gcloud-guardrails denylist.The active project is ambient state the user may not be looking at, and on a multi-project machine it is often not the one they mean.
Pass the location flag (--region, --zone, --location) the resource needs.An omitted location triggers an interactive prompt, which hangs a non-interactive agent.
Add --quiet to commands that would prompt, only once the command is read-only or authorised, and never to a denylisted command.--quiet accepts defaults, including "yes" to destructive prompts. It is never a way round authorisation.
Add --async to long-running operations that support it, then poll with describe.Avoids tool-call timeouts on cluster or instance creation.
Preserve every flag the user specified in each proposed command.Dropping --project or --impersonate-service-account silently retargets the command.

If a location is unknown, discover it read-only first (for example gcloud run services list --project=PROJECT_ID --format="value(metadata.name,region)" --limit=20), then ask the user if more than one candidate remains.

Data reduction

Unbounded output exhausts the context window and hides the answer. Every list and every describe of a large resource carries at least one of:

  • Projection — --format="json(name,status,createTime)" or --format="value(name)"
  • Limit — --limit=N
  • Server-side filter — --filter="status=RUNNING AND labels.env=prod"

Never run a bare list. To learn a resource's field names before projecting, fetch one record: gcloud <group> <resource> list --project=PROJECT_ID --limit=1 --format=json.

Authorisation

Permission is decided by what a command does, not by how it is spelt. The default is stop and ask.

ClassExamplesRule
Read-onlyhelp, list, describe, get-iam-policy, config list, logging read, --dry-run, --validate-onlyRun under the execution rules.
Consequential — anything that creates, changes, stops, removes or billscreate, deploy, update, patch, set-*, stop, reset, resize, rm, remove, disable, import, applyPropose the exact command and its effect, then wait for a named human to authorise it.

When unsure which class a command is, treat it as consequential. A cost-warning comment or a successful dry run is information for the human, not approval. Authorisation covers the exact command shown; a changed flag needs a fresh yes.

Denylist — never autonomous, never --quiet

These are consequential commands with outsized blast radius. In addition to the rule above: never chain them into a plan as a step that "will run", never add --quiet to them, and route IAM changes through the iam skill and the security gate.

Command patternRisk
Any IAM change: add-iam-policy-binding, remove-iam-policy-binding, set-iam-policy, iam roles create/update, iam service-accounts keys createPrivilege escalation or lock-out. Route through the iam skill and the security gate.
gcloud * delete, gcloud storage rm, any other remove or purgeIrreversible destruction.
gcloud billing *Service disruption or unbounded cost.
gcloud organizations *, gcloud resource-manager folders *Changes reach every project beneath.
gcloud kms * (destroy, disable, rotate)Can make data permanently unreadable.
gcloud infra-manager deployments applyAutonomous IaC change with no review.
gcloud services enableEnabling an API can start billing. Assume needed APIs are on; if a call fails with a disabled-API error, report it and ask.
Installing or updating the gcloud CLI or its componentsHost modification. Ask first.

Billable creates that are not on the denylist (a Cloud Run deploy, a VM) still need authorisation, and the proposal carries the ADR-004 comment and cost warning:

# Billable action — confirm cost before running
gcloud run deploy SERVICE --image=IMAGE --region=REGION --project=PROJECT_ID --quiet

Worked example

User: "Create a Cloud SQL Postgres instance for staging."

  1. gcloud help sql instances create
  2. Required: instance name, --database-version, --tier or --cpu/--memory, --region. No --dry-run support.
  3. No dry run available — say so.
  4. Consequential and billable, not on the denylist. Propose it and wait for authorisation:
# Billable action — confirm cost before running
gcloud sql instances create INSTANCE_NAME \
  --database-version=POSTGRES_16 \
  --tier=db-custom-1-3840 \
  --region=REGION \
  --project=PROJECT_ID \
  --async

Then gcloud sql operations list --instance=INSTANCE_NAME --project=PROJECT_ID --limit=1 --format="value(name,status)" to track it.

References

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.