When an agent hits a 403 PERMISSION_DENIED on Google Cloud, it usually starts guessing roles or asks for roles/editor to get unstuck. iam-helper-for-troubleshooting, which Google released on October 26, 2026 alongside three other IAM skills, does the opposite: it takes the error ID from the response, asks Policy Troubleshooter which policy is in the way, and grants nothing without a human signing off.
What it does and when it kicks in
The skill has two modes and picks one based on who's calling:
- Requester, for the blocked developer or service account. It captures the
error_info_id(or the principal, permission and resource), tries to diagnose the denial itself, activates a Privileged Access Manager (PAM) grant if a pre-approved entitlement exists and, when it can't fix things, writes a structured ticket for an admin with the blocking policy and a suggested role. - Resolver, the default, for whoever runs IAM. It walks the whole hierarchy (organization, folder, project) and separates three causes: an IAM v2 deny policy, a Principal Access Boundary (PAB) policy, or simply a missing binding in the allow policy.
The stop rules are the best part. If the result is GRANTED, even through inheritance from the organization, the skill reports that the configuration is correct and ends there, without suggesting roles. If it's UNKNOWN because it can't expand group memberships (that needs roles/browser), it says so and stops too. And if the troubleshooting call itself returns a 403, it halts instead of looping through alternative commands. Those are exactly the three spots where an unguided agent tends to end up over-granting.
When a role really is missing, the skill asks before it even lists candidates, reminds you that a deny policy beats any allow (granting a role won't help without an exception), and offers two paths: temporary access through PAM, handed off to the sibling iam-helper-for-privileged-access-management skill, or a permanent binding.
Installing it and what it needs
It comes from Google's catalog, which asks you to pick the skills, the agent (Claude Code, Gemini CLI, Cursor…) and the scope:
npx skills add google/skillsTo diagnose, the agent's identity needs roles/policyintelligence.policyTroubleshooterViewer (or roles/iam.securityReviewer), roles/iam.principalAccessBoundaryViewer and roles/serviceusage.serviceUsageConsumer. To fix things, it needs roles/resourcemanager.projectIamAdmin or roles/iam.denyAdmin. With only the first set, the skill diagnoses and escalates; it can't grant anything.
It prefers Google's managed Policy Troubleshooter MCP server (https://policytroubleshooter.googleapis.com/mcp, with the troubleshoot_access and troubleshoot_iam_error_id tools). If that isn't set up, it falls back to two Python scripts or to gcloud:
gcloud policy-troubleshoot iam //cloudresourcemanager.googleapis.com/projects/my-project \
--principal-email="[email protected]" \
--permission="bigquery.datasets.create" \
--billing-project="my-project" \
--format=jsonRisks and limits
I read both scripts and the reference files. Every IAM change, even a read-only role, needs explicit confirmation, and admin roles come with an extra high-risk warning. The fine print is in what happens before that:
troubleshooting_error_id.pyenables an API without asking. Before callingv3beta/iam:troubleshootErrorit runsgcloud services enable policytroubleshooter.googleapis.comon the project it pulls out of the error ID. Harmless, but it's a write to your project that skips the approval step.- The "least privileged" role isn't always the least privileged.
least_privileged_role.pydrops basic roles, but it ranks standard service roles (names ending inadmin,editor,viewer…) first and only then sorts by permission count. That's deliberate, since the skill's guidelines prefer standard roles, but it can suggestroles/compute.adminwhere a smaller role would do. Check the suggestion before you approve it. - It tags your usage. Every command it runs carries
CLOUDSDK_METRICS_REQUEST_ATTRIBUTIONor aUser-Agentsuffix with the skill name and version. The file says no user data is included, and you can turn it off by asking the agent. - The sample MCP config won't work as written. It puts
Bearer $(gcloud auth print-access-token)inside JSON, where no shell ever expands the$(...). Follow the linked connection guide instead of copying it.
The approval rules (references/guardrails.md) are meant to be customized by each organization: out of the box everything needs confirmation, but nothing stops someone from loosening them.
Versus doing it by hand
The diagnosis itself is the same one you get from gcloud policy-troubleshoot iam or Policy Troubleshooter in the console: the skill sees nothing you can't. What it adds is the judgment around it: knowing when to stop, telling deny, PAB and allow apart before touching anything, preferring temporary PAM access, and leaving a complete ticket when it can't fix the problem itself. For a team that already lets an agent deploy to GCP, that discipline is what keeps roles/editor from becoming the shortcut.
The other three skills round out the loop: iam-helper-for-policy-management creates and validates allow and deny policies and blocks allUsers and basic roles; iam-helper-for-policy-simulator tests a change against the last 90 days of access logs before applying it; and iam-helper-for-privileged-access-management handles temporary PAM grants.
Sources
- google/skills: iam-helper-for-troubleshooting
- Scale agents securely with IAM Helper Agent Skills and MCP Tools (Google Cloud Blog, October 26, 2026)