Guide · Agent skill
How to use the IAM Access Troubleshooter agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The IAM Access Troubleshooter is an agent skill for Google Cloud that helps an AI agent investigate 'permission denied' errors, such as HTTP 403 responses or Error IDs. It is useful for developers who are blocked by access problems and for administrators who handle escalated IAM tickets. After this guide you will know what the skill does, how to install it, how to phrase requests so it triggers, and what it needs to run safely.
IAM Access Troubleshootergoogle/skills · Apache-2.0 Download the skill Quick start
- 1Check requirements. Confirm gcloud is installed and authenticated, and that Python 3 is available.
- 2Download the ZIP. Get the skill archive from this page.
- 3Unzip the skill. Extract it into ~/.claude/skills/ for personal use or .claude/skills/ inside a project.
- 4Or upload in the Claude apps. Go to Settings → Capabilities → Skills and upload the skill there.
- 5Make a request. Describe the denied action, including any Error ID, in plain language.
- 6Answer approval prompts. Confirm before the agent lists roles or provisions any access.
What is an agent skill?
An agent skill is a folder of instructions and optional scripts that an AI agent can load when a task matches it. The skill's SKILL.md file describes when to use it and how to proceed, and supporting files hold detailed playbooks and guardrails.
What does the IAM Access Troubleshooter make the agent do?
The skill teaches the agent to work out why Google Cloud refused access. It uses Google's Policy Troubleshooter to analyse allow, deny and Principal Access Boundary policies, and it can use the error ID from a Console or API error message to look up the cause.
The skill has two modes. Requester Flow is for developers who hit an access denial: it captures the error context, can self-activate PAM just-in-time grants, can self-remediate if the developer is already elevated, or can write a structured ticket. Resolver Flow is for administrators: it evaluates policies, can create deny exemptions, looks for the smallest role that grants a permission, and can provision PAM or IAM access.
The skill is built to stop and ask for human approval before any access change. If access is already granted, or the state is unknown, the agent ends the troubleshooting flow instead of probing further.
How do you install the skill?
Download the skill ZIP from this page and unzip it. For a personal setup, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.
In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/iam-helper-for-troubleshooting
- Project: .claude/skills/iam-helper-for-troubleshooting
What do you need before it works?
The skill runs real gcloud commands and bundled Python scripts, and it makes network calls. Check these requirements first.
- Google Cloud SDK (gcloud) installed and authenticated
- Python 3 to run the bundled scripts
- IAM permissions to call Policy Troubleshooter and list roles, plus roles/browser for group expansion
How do you trigger the skill with a natural request?
Describe the problem in plain language and include whatever identifiers you have. The agent chooses the mode from your context: a developer blocked during a task gets Requester Flow, and a request to troubleshoot access or find candidate roles defaults to Resolver Flow.
- I got a 403 permission denied when calling BigQuery from my service account. Error ID is attached.
- Why does my user get access denied on this project bucket? Check with Policy Troubleshooter.
- Find the smallest role that lets this principal create Pub/Sub topics on project X.
- Help me write an access request ticket for this denied permission.
What happens during a session?
Expect the agent to ask before it lists or searches roles, and to pause for approval before provisioning anything. If the answer is that access is already granted, the agent will tell you the configuration is correct and stop there. If the caller gets PERMISSION_DENIED on their own identity, the agent stops without trying alternative commands.
What safety rules should you know?
The skill runs scripts and uses the network, so review what it will run before approving. Every gcloud, REST or MCP command is tagged with a usage attribution prefix that names only the skill and its version; the tag is set inline on each command rather than saved with gcloud config set.
Use the skill only with accounts you are authorised to administer. It is designed around approvals, but it executes real commands. Before using it in an organisation, review and customise references/guardrails.md, because the default approval tiers are generic.
- Scripts: scripts/least_privileged_role.py and scripts/troubleshooting_error_id.py
- Remote MCP server used by Policy Troubleshooter: https://policytroubleshooter.googleapis.com/mcp
- Do not rely on the default approval tiers without reviewing them
What are good tips for using it well?
Give the complete Error ID and the principal, resource and permission involved. Specific input lets Policy Troubleshooter give a clear answer and avoids extra queries.
Read references/guardrails.md before rolling the skill out to a team, and decide which roles fall into each approval tier.
- Keep the full error message or Error ID handy
- State whether you are a developer requesting access or an administrator resolving a ticket
- Expect the agent to pause for confirmation before listing roles
What people use it for
- A developer gets a 403 from a Cloud Storage call and needs to know which principal or permission is missing.
- An administrator works through an escalated IAM ticket using an Error ID from a Console message.
- A team looks for the smallest predefined role that grants one permission, then documents the request.
- A developer prepares a structured access request ticket for an administrator to review.
Frequently asked questions
How do I install the IAM Access Troubleshooter skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
What do I need to run the iam-helper-for-troubleshooting skill?
You need the Google Cloud SDK (gcloud) installed and authenticated, Python 3 to run the bundled scripts, and IAM permissions to call Policy Troubleshooter and list roles. Roles/browser is needed for group expansion.
Is the IAM Access Troubleshooter skill free?
The skill is published under the Apache-2.0 licence. This page does not state any price, so check the licence and the source repository for terms.
Does the skill change permissions automatically?
No. The skill is designed to ask for human approval before any role provisioning, and it stops when access is already granted or the state is unknown. Organisations should customise references/guardrails.md first.
Can I use this skill outside Google Cloud?
No. The skill is specific to Google Cloud IAM and Policy Troubleshooter, so it is not suited to other cloud environments.
What if the agent gets Permission Denied on my own account?
The skill stops immediately without querying roles or running alternative commands. Check that the account you are using has the permissions needed to call Policy Troubleshooter, then try again.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits developers stuck on Google Cloud permission errors who want a guided diagnosis, and administrators who want a structured way to find least-privilege roles with approvals. It is a poor fit for non-Google Cloud environments, for anyone trying to get around access controls, or for organisations that have not reviewed the default guardrails.
Download the skill