How to use the Cloud Storage 403 Diagnostic agent skill

What does the skill make the agent do?

Once installed, the agent follows a structured diagnostic procedure for access-denied problems. It identifies the principal (a user or service account) trying to reach a resource, the target bucket or object, the operation attempted, and the authentication mechanism used. It then checks likely causes such as IAM permissions, ACLs, VPC Service Controls perimeters, IAM Deny policies, Bucket IP Filtering and credential mismatches, and explains what it found.

The skill's own guide tells the agent to check whether Uniform Bucket-Level Access (UBLA) is enabled before looking at object ACLs, because when UBLA is enabled object-level ACLs are ignored.

• Clarifies the principal, target resource, operation and authentication method
• Checks IAM bindings, ACLs, UBLA, perimeters and credentials
• Explains the likely root cause in plain terms
• Proposes a fix only after you approve it

Install the skill from a ZIP file

Download the ZIP for the skill from this page. The skill's files are SKILL.md and references/403_troubleshooting.md. Unzip the archive into one of these locations, depending on how you want to use it:

• Personal use across projects: ~/.claude/skills/
• Single project: the .claude/skills/ folder inside your project
• Claude apps: upload the ZIP under Settings → Capabilities → Skills

Install the Google Cloud CLI and check access

The skill runs gcloud inspection commands against your project, so you need the Google Cloud CLI (gcloud) installed. The source links to the Google Cloud CLI Installation Guide for setup. You also need access to the project and bucket you are diagnosing, with credentials that can run gcloud storage commands. Curl is optional and only needed for direct HTTP calls.

How to ask for help with natural requests

You do not need special syntax. Describe the failing call, the principal and the resource. The agent will ask for anything it is missing, such as the principal's email, the bucket or object path, or the exact error text. Requests the skill is built for include:

• "My service account gets 403 Permission Denied when reading gs://my-bucket/reports/. Why?"
• "Why can this user list objects in the bucket but not delete them?"
• "Our VPC Service Controls perimeter may be blocking Cloud Storage access. Can you check?"
• "Signed URLs for this bucket return SignatureDoesNotMatch. What is wrong?"
• "Explain why get-iam-policy returns 403 on this bucket."

Understand the approval step

The skill's safety rule is that the agent must never run a command that changes state or configuration without your prior approval. Before any change, it prints the exact command, explains the proposed change, and asks for confirmation such as "Do you approve executing this command? [Y/N]". Each approval covers only that single command. Commands the source names as state-changing include gcloud storage buckets add-iam-policy-binding and gcloud storage buckets update.

The agent is also told not to loop on inspection commands. If gcloud storage buckets get-iam-policy returns 403, it should first rule out perimeter controls such as VPC-SC or IP Filtering, since granting IAM roles will not fix a perimeter block. If perimeters are not the cause, the caller likely lacks the storage.buckets.getIamPolicy permission. The skill recommends the least-privilege role roles/iam.securityReviewer, or a custom role that contains that permission, and says not to use roles/storage.bucketViewer or roles/storage.admin for this.

Attribution tags on commands

The skill requires every gcloud command it runs or suggests to carry a metrics environment variable that labels the activity as coming from this skill. The variable is set inline on each command, not with gcloud config set, so the label does not persist after the task. Curl calls must include a User-Agent header. You do not need to write these yourself, but you will see them in the commands the agent shows you.

Safety notes: scripts and network

This skill runs scripts and uses the network. Its diagnosis depends on running gcloud inspection commands against your Google Cloud project, so it will send requests to Google Cloud on your behalf using your credentials. Review each command before you approve it. Its scope is troubleshooting denials only, so it is not a general security audit tool, and it should not be used for Cloud Storage FUSE mounts.

• Use an account that has only the access you need for diagnosis
• Read each proposed command before answering Y
• Do not approve a command you do not understand
• Remember that an approval covers one command only