Skip to main content
skill CX Codex official · Google

google-cloud-storage-diagnostic — Claude Code skill for GCS errors

The google-cloud-storage-diagnostic Claude Code skill diagnoses Cloud Storage access denials and permission conflicts. It activates for questions about a bucket or object returning 403, including requests that need analysis but no commands.

Apache-2.0 ★ 24,522 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add google/skills --skill google-cloud-storage-diagnostic -a claude-code
Open on GitHub

What google-cloud-storage-diagnostic does

The skill investigates why Cloud Storage rejects a read, write, listing, or delete operation on a bucket or object. It covers 403 errors and IAM or ACL conflicts, along with access issues involving Signed URLs, VPC Service Controls, IP filtering, Requester Pays, and other controls.

For 403 diagnosis, it consults references/403_troubleshooting.md. Cloud Storage commands must carry attribution tags. Any command that changes configuration requires separate user approval: the agent must show the exact command and explain the proposed change first. The available instructions also address denied bucket IAM policy inspection: they say not to retry the request and suggest roles/iam.securityReviewer or a custom role containing storage.buckets.getIamPolicy.

What it helps with

  • diagnose a 403 while reading an object
  • trace a bucket's IAM and ACL conflict
  • identify a VPC Service Controls access block
  • find why object deletion is denied

Example prompts for the agent

  • Diagnose the 403 when reading gs://{bucket_name}/{object_path}
  • Why does gcloud storage buckets get-iam-policy return an access denial?
  • Check for an IAM and ACL conflict on gs://{bucket_name}

How to install google-cloud-storage-diagnostic

1Skills CLI (Vercel)

npx skills add google/skills --skill google-cloud-storage-diagnostic -a claude-code

2Manually: put the files in place

~/.claude/skills/google-cloud-storage-diagnostic/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/google-cloud-storage-diagnostic/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about google-cloud-storage-diagnostic

How do I install google-cloud-storage-diagnostic in Claude Code?

Run npx skills add google/skills --skill google-cloud-storage-diagnostic -a claude-code. The skill file is at ~/.claude/skills/google-cloud-storage-diagnostic/SKILL.md.

What does google-cloud-storage-diagnostic do?

It helps diagnose Cloud Storage access failures and permission conflicts, including 403 errors on buckets and objects. For 403 cases, it uses references/403_troubleshooting.md.

Does the skill need approval before changing Cloud Storage settings?

Yes. Before running a configuration-changing command, the agent must display the full command, explain the proposed change, and ask for approval. Approval covers that command only.

Source text

SKILL.md · Apache-2.0
---
name: google-cloud-storage-diagnostic
description: >-
  Troubleshoots and diagnoses Cloud Storage on Google Cloud (also known
  colloquially as GCS) access and permission denials (403 Permission Denied or
  Insufficient Permission) and access control conflicts. Use whenever a user
  encounters or asks
  to analyze a 403 error on a bucket or object - including analysis-only
  questions where no commands are run - or needs help with IAM bindings,
  fine-grained ACLs, Uniform Bucket-Level Access (UBLA), getIamPolicy
  inspection denials and least-privilege inspection roles, browser
  storage.cloud.google.com Cookieauth and Data Access Audit Logging conflicts,
  Signed URL SignatureDoesNotMatch errors, VPC Service Controls (VPC-SC)
  perimeters, explicit IAM Deny policies, Bucket IP Filtering, Requester Pays,
  Retention Policy locks, Compute Engine VM access scopes, Application Default
  Credentials (ADC) mismatches, recursive delete permissions, or recreated
  service accounts. Don't use for creating buckets, routine uploads/downloads,
  proactive security audits, or Cloud Storage FUSE mounts.
license: Apache-2.0
metadata:
  version: "1.0.1"
  publisher: google
  tags: "gcs, storage, troubleshooting, diagnostic, iam, 403, permissions"
  category: Storage
  support_tier: primary
---

# Cloud Storage Diagnostic

> [!CAUTION]
>
> **CRITICAL SAFETY MANDATE: NO AUTO-EXECUTION OF REMEDIATION COMMANDS**
>
> **NEVER execute any state-modifying, configuration-changing, or remediation
> commands** (such as `gcloud storage buckets add-iam-policy-binding`, `gcloud
> storage buckets update`, ACL modifications, or object/bucket updates)
> **autonomously or without prior user approval.**
>
> **RATIONALE & BLAST RADIUS**: Cloud Storage security configurations (IAM
> policy bindings, bucket IP filters, UBLA settings, retention policies) carry
> an extremely high blast radius. Unapproved modifications can accidentally
> grant unauthorized public access, leak sensitive data, lock out administrative
> users, or breach organizational compliance boundaries.
>
> Before executing ANY command that modifies state or configuration: 1. You MUST
> print the exact command and explain the proposed configuration change to the
> user. 2. Even when proposing or recommending a remediation command, you MUST
> explicitly ask the user for confirmation (for example, "Do you approve
> executing this command? [Y/N]"). 3. You MUST wait for explicit user approval
> before executing any remediation command. 4. User approval applies ONLY to
> that single command; EVERY subsequent command execution requires separate
> explicit user confirmation.

You are a Cloud Storage on Google Cloud diagnostic and troubleshooting agent
specialized in systematically identifying root causes for access denials and
configuration conflicts, and proposing actionable remediation commands.

## Use Diagnostic Resources

When diagnosing Cloud Storage issues, identify the problem type and consult the
relevant diagnostic resource guide before proceeding:

Problem Area              | Description                                                                                                                               | Diagnostic Guide
:------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------- | :---------------
**403 Permission Denied** | Principal (User or Service Account) receives a `403 Permission Denied` error when reading, writing, listing, or deleting buckets/objects. | [`references/403_troubleshooting.md`](references/403_troubleshooting.md)

--------------------------------------------------------------------------------

## Apply Attribution Tags

For Google Cloud CLI (`gcloud` CLI) installation, see the
[Google Cloud CLI Installation Guide](https://docs.cloud.google.com/sdk/docs/install-sdk.md.txt).

**CRITICAL RULE: You MUST tag EVERY Cloud Storage command you run
(`run_command`) or suggest to the user.**

-   **gcloud commands:** Prefix every `gcloud` invocation, whatever the
    subcommand, with the metrics environment variables. Set them inline on each
    command; shell state may not persist between commands. Use this append form
    verbatim. It keeps any attribution the host environment already set (for
    example an IDE plugin tagging agent activity through the same variable) and
    adds the skill tag after it, so neither value clobbers the other:

    ```bash
    CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-diagnostic)" \
        gcloud <command> [flags]
    ```

    Do not use `gcloud config set` for this: it would persist beyond the current
    task and mislabel unrelated usage.

-   **curl commands:** For direct HTTP calls (such as `curl`), you MUST pass the
    explicit `-H "User-Agent: ..."` header in the shell command syntax exactly
    like this:

    ```bash
    curl -H "User-Agent: gcs-skills/1.0 (skill:google-cloud-storage-diagnostic)" ...
    ```

-   For client libraries, Terraform, and Cloud Storage FUSE, use the user-agent
    options shown in the corresponding references.

## Follow the Diagnostic Workflow

Whenever a user requests assistance diagnosing a Cloud Storage issue:

### Step 1: Clarify Context and Scope

-   Clarify the exact principal (`user:{email}` or `serviceAccount:{email}`)
    experiencing the issue.
-   Clarify the target resource (`gs://{bucket_name}` or
    `gs://{bucket_name}/{object_path}`).
-   Identify the attempted operation (such as read object, write object, list
    bucket contents, or delete object).
-   Identify the authentication mechanism (such as Signed URL, Cookieauth, OAuth
    token, or Impersonation).

### Step 2: Consult Specific Diagnostic Guide

-   If the issue involves a **403 Permission Denied** error or IAM/ACL denial,
    immediately consult and execute the step-by-step diagnostic procedures
    documented in
    [`references/403_troubleshooting.md`](references/403_troubleshooting.md).
-   If running `gcloud storage buckets get-iam-policy` returns 403 Permission
    Denied, DO NOT loop or retry inspection commands on the bucket. First verify
    that perimeter security controls (such as VPC-SC or IP Filtering) are not
    blocking access as detailed in `403_troubleshooting.md`, because granting
    IAM roles will not resolve perimeter blocks. If perimeters are not the
    cause, recognize that the diagnostic caller lacks inspection permissions
    (`storage.buckets.getIamPolicy`). Recommend granting the least-privilege
    role `roles/iam.securityReviewer` (or a custom role containing
    `storage.buckets.getIamPolicy`); never recommend
    `roles/storage.bucketViewer` (which does not grant IAM policy access) or
    `roles/storage.admin`. Propose how to remediate inspection access or
    fallback to project-level IAM policy checks as outlined in
    `403_troubleshooting.md`.

### Step 3: Propose Remediation with User Confirmation

-   Synthesize your findings and explain *why* the access or operation failed
    (such as missing IAM role, UBLA restriction, legacy ACL mismatch, or VPC-SC
    block).
-   Provide the exact `gcloud` remediation command.
-   *Always include an explicit confirmation prompt (for example, "Do you
    approve executing this command? [Y/N]") and wait for explicit Y/N
    confirmation before executing any modification or remediation command on
    behalf of the user.*

## Phase Summary

### 1. Discover Scope & Telemetry

-   **Inputs:** User input (principal, bucket/object URI, error text)
-   **Outputs:** Target scope, UBLA vs ACL classification
-   **Reference Section:** `references/403_troubleshooting.md` Steps 1-2

### 2. Telemetry & Policy Eval

-   **Inputs:**
    `CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT
    }gcs-skills..." gcloud storage buckets describe / get-iam-policy`
-   **Outputs:** Active IAM roles, VPC-SC alerts, Deny policies
-   **Reference Section:** `references/403_troubleshooting.md` Steps 3-7

### 3. Edge-Case Root Cause Isolation

-   **Inputs:** Advanced signals (`requesterPays`, `retentionPeriod`, ADC)
-   **Outputs:** Root cause diagnosis
-   **Reference Section:** `references/403_troubleshooting.md` Step 8

### 4. Prescriptive Remediation

-   **Inputs:** Root cause diagnosis
-   **Outputs:** Tagged `gcloud` remediation command + Y/N prompt
-   **Reference Section:** `Apply Attribution Tags` section & Step 8

## Error Handling Matrix

The following list provides common Cloud Storage 403 scenarios and the
prescriptive response you MUST give. Use this exactly.

### `Permission 'storage.buckets.getIamPolicy' denied`

-   **Cause:** Diagnostic caller lacks `storage.buckets.getIamPolicy` permission
    (such as missing `roles/iam.securityReviewer`), or request is blocked by
    perimeter security controls (VPC-SC / IP Filtering).
-   **Fix:** **DO NOT LOOP OR RETRY.** First check whether perimeter security
    controls (such as VPC-SC or IP Filtering) are blocking access; do not
    blindly prescribe role grants when perimeters are involved. If perimeters
    are not the cause, explain that the account executing the check lacks bucket
    IAM inspection permissions. Recommend granting the least-privilege role
    `roles/iam.securityReviewer` or a custom role containing
    `storage.buckets.getIamPolicy` (never `roles/storage.bucketViewer` or
    `roles/storage.admin`).

### `Bucket is requester pays bucket but no user project provided`

-   **Cause:** `requesterPays: true` enabled on target bucket
-   **Fix:** **DO NOT LOOP OR RETRY.** Even with full `objectViewer` roles,
    requests must pass billing project. Prescribe `--billing-project=PROJECT_ID`
    or `-u PROJECT_ID`.

### `Request is prohibited by organization's policy. vpcServiceControlsUniqueIdentifier`

-   **Cause:** Request blocked by VPC Service Controls (VPC-SC) service
    perimeter
-   **Fix:** Inform user that adding IAM roles cannot bypass a VPC-SC perimeter.
    Direct user to Organization/Project Administrator to update ingress/egress
    rules.

### `Request is prohibited by organization's policy.` (No VPC-SC ID)

-   **Cause:** Organization Policy constraint (such as
    `constraints/storage.publicAccessPrevention` or
    `constraints/gcp.resourceLocations`) or a VPC-SC perimeter block without a
    logged UUID
-   **Fix:** Inspect active Organization Policy constraints (`gcloud
    org-policies list --project=PROJECT_ID`) or check Cloud Audit Logs for
    perimeter rejections, and direct the user to the Organization/Project
    Administrator.

### `Permission '...' denied ... due to an IAM deny policy` (or `403` despite `roles/storage.admin` allow bindings)

-   **Cause:** Organization, Folder, or Project IAM Deny policy
    (`iam.googleapis.com/DenyPolicy`) explicitly denies the permission
-   **Fix:** Explain that explicit IAM Deny policies take absolute precedence
    over standard allow roles (including `roles/storage.admin`) and cannot be
    bypassed. Advise checking Deny policies (`gcloud iam policies list
    --attachment-point=cloudresourcemanager.googleapis.com/projects/PROJECT_ID
    --kind=denypolicies`, and `--attachment-point=organizations/ORG_ID` if
    needed) and contacting the Organization Administrator.

### `403 Insufficient Permission` on a Compute Engine VM despite correct IAM roles

-   **Cause:** Legacy GCE VM Access Scopes (`devstorage.read_only`) restrict
    OAuth token scopes
-   **Fix:** **DO NOT RUN LIVE INSPECTION COMMANDS ON FICTIONAL VMS.** Explain
    immediately that GCE access scopes throttle OAuth tokens regardless of IAM
    roles. Advise stopping the VM (`gcloud compute instances stop INSTANCE`),
    setting scopes to `cloud-platform` (`gcloud compute instances
    set-service-account INSTANCE --scopes=cloud-platform`), and restarting the
    VM (`gcloud compute instances start INSTANCE`).

### `403 Permission Denied` on object delete despite `roles/storage.admin`

-   **Cause:** Bucket has an active Retention Policy (`retention_policy`)
-   **Fix:** Explain that retention locks act as un-bypassable data protection
    holds and cannot be overridden by IAM until the retention timestamp expires.

### `403 Permission Denied` on recreated Service Account with exact same email

-   **Cause:** Account deleted and recreated generates a new underlying Unique
    ID
-   **Fix:** Instruct user to remove the old IAM policy binding and re-add the
    exact same binding so IAM registers the new Unique ID.

### `403 Permission Denied` due to Bucket IP Filter

-   **Cause:** The bucket has `ip_filter_config` configured with `mode:
    "Enabled"`, blocking the caller's IP address and preventing live metadata
    checks.
-   **Fix:** Route diagnostic queries through Cloud Audit Logs to confirm the IP
    filter violation:

    ```bash
    CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-diagnostic)" \
        gcloud logging read "resource.type=gcs_bucket AND resource.labels.bucket_name=\"{bucket_name}\" AND protoPayload.authenticationInfo.principalEmail=\"{principal_email}\"" --project="{project_id}" --limit=5 --format=json
    ```

    If `gcloud logging read` returns permission errors (`403`), `Project not
    found or deleted`, an empty array `[]`, or only unrelated Admin Activity
    entries (`cloudaudit.googleapis.com%2Factivity`) with zero Data Access
    entries (`cloudaudit.googleapis.com%2Fdata_access`) for the failing
    operation, do not loop or retry. Immediately halt technical diagnosis,
    inform the user that they lack visibility into the Cloud Audit Logs (due to
    permissions, disabled Data Access logging, or log exclusions) and cannot
    definitively diagnose advanced network denials, suggest that Bucket-Level IP
    Filtering or VPC Service Controls may be blocking access, and direct them to
    ask a Project/Organization Administrator to check the Cloud Audit Logs
    (including `protoPayload.status.code=7` and
    `vpcServiceControlsUniqueIdentifier`) or enable Data Access Audit Logs.

    **Remediation:** Do not write ad-hoc CLI commands. Refer to Step 8 in
    `references/403_troubleshooting.md` for proper instructions to fetch the
    existing `ip_filter_config`, append the caller's CIDR to
    `allowedIpCidrRanges` in `ALLOWED_IPS.json` without overwriting existing
    ranges, and apply it via the `gcloud storage buckets update` command.

### `403 Permission Denied` on `storage.cloud.google.com` in Browser (Cookieauth)

-   **Cause:** Browser downloads via the `storage.cloud.google.com` domain use
    Google Account cookie authentication, also known as `Cookieauth`. Having
    Data Access Audit Logging (`DATA_READ` / `DATA_WRITE` for
    `storage.googleapis.com`) enabled on the project conflicts with Cookieauth
    and causes consistent 403 errors in the browser (or multiple logged-in
    Google Accounts send the wrong identity cookie).
-   **Fix:** Inspect the bucket IAM policy/configuration and check the project's
    audit log configuration using:

    ```bash
    CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-diagnostic)" \
        gcloud projects get-iam-policy {project_id} --format="json(auditConfigs)"
    ```

    Explain that Data Access Logging conflicts with Cookieauth when accessing
    objects via `storage.cloud.google.com` in the browser. Advise accessing
    objects via `gcloud`, API endpoints (`storage.googleapis.com`), or Signed
    URLs to bypass browser cookie authentication limitations (or testing in an
    Incognito window / adjusting Data Access Audit Logging if browser access is
    required).

### `404 Not Found` or `Bucket does not exist`

-   **Cause:** Target bucket does not exist or was deleted
-   **Fix:** **DO NOT LOOP OR RETRY.** Stop trying to execute live commands on
    the missing bucket. Acknowledge the bucket is missing, but proceed to
    explain your diagnosis hypothetically based on the provided scenario
    context.

© google · Apache-2.0 · google/skills

Similar skills

All skills for Cloud: AWS, Azure, GCP →

From the same set203

The whole set →
compute-host-events-troubleshooting compute-host-events-troubleshooting is a Claude Code skill that diagnoses unexpected Google Compute Engine VM reboots, crashes, and preemptions. CX Codex +1 ★ 24,522repo stars litert-google-tensor The litert-google-tensor Claude Code skill compiles LiteRT models for Google Tensor TPUs and checks their performance on a Pixel. It can also package a compiled model for an Android Gradle app. CX Codex +1 ★ 24,522repo stars pathways-workload pathways-workload — a skill for Claude Code debugs failed or hung Pathways on Cloud GKE workloads. Runs when JAX TPU training halts, containers crash, or IFRT proxy connections drop. CX Codex +1 ★ 24,522repo stars iap-agent-platform-troubleshooting The iap-agent-platform-troubleshooting Claude Code skill diagnoses IAP denials on outbound requests from Gemini Enterprise Agent Platform agents. Run it for Egress request is not authorized or suspected access-policy blocks. CX Codex +1 ★ 24,522repo stars developer-device-platform-device-run developer-device-platform-device-run is a Claude Code skill for running batch jobs on remote Android devices. It activates for a binary, shell script, or instrumentation test without an interactive session. CX Codex +1 ★ 24,522repo stars compute-vm-creation The compute-vm-creation skill automates planning and provisioning of standalone Google Compute Engine VMs. It assists in configuring hardware, regional placement, and network settings via CLI or MCP tools. CX Codex +1 ★ 24,522repo stars compute-spot-capacity-advice The compute-spot-capacity-advice Claude Code skill assesses Google Compute Engine Spot VM capacity and placement. It runs during batch planning, when comparing machine families or regions. CX Codex +1 ★ 24,522repo stars cloud-operator Delegates Google Cloud infrastructure operations to Cloud Operator via the autocloud MCP server. Triggers before modifying local Terraform or Kubernetes configs. CX Codex +1 ★ 24,522repo stars

Project sponsors

Companies that keep this analytics open