Guide · Agent skill
How to use the IAM Policy Simulator Helper agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The IAM Policy Simulator Helper is an agent skill, a packaged set of instructions and a helper script that an AI agent such as Claude loads when you ask it to change Google Cloud access rules. It is for cloud administrators and platform teams who want to tighten or change IAM roles without breaking services that are already running. After this guide you will know how to install the skill, how to phrase a request that triggers it, and what the agent checks before it touches a policy.
IAM Policy Simulator Helpergoogle/skills · Apache-2.0 Download the skill Quick start
- 1Download and unzip the skill. Download the skill ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ for personal use, or in a project's .claude/skills/ folder.
- 2Install gcloud and Python 3. Make sure the Google Cloud CLI is installed and authenticated, and that Python 3 is available to run the helper script.
- 3Confirm IAM roles and the API. Check that your identity has roles/policysimulator.admin, roles/cloudasset.viewer and an IAM Admin role on the target. Enable the Policy Simulator API when the CLI prompts you.
- 4Ask for a specific change. Name the resource type, its ID, and the role or member change you want, and ask for it to be simulated before applying.
- 5Review the simulation result. Wait for the agent to run scripts/analyze_simulation.py. Only continue if it reports no disrupted access and REVOKED_COUNT is 0.
- 6Confirm or decline the apply. Answer Yes or No to the apply prompt. Declining ends the workflow, and the temporary files are removed either way.
What the skill makes the agent do
When the skill is active, the agent follows a fixed plan, simulate, analyze, apply workflow before it changes who can access a Google Cloud project, folder, or organization. It first saves the current IAM v1 allow policy, then prepares a proposed version with the role bindings you asked for. It replays the last 90 days of access logs against the proposed policy using Google's Policy Simulator.
If the simulation finds access that would be revoked or may be revoked, the agent does not apply the change and reports the principal, permission and resource affected. Only when no disrupted access is found does it ask you to confirm before applying the change. Afterwards it deletes its temporary files.
- Saves the current policy to /tmp/current_policy.json
- Writes the proposed policy to /tmp/proposed_policy.json
- Stops if the change is a no-op, meaning nothing would actually change
- Runs scripts/analyze_simulation.py on the results and checks REVOKED_COUNT
- Asks Yes/No before applying, and cleans up temporary files at the end
Install the skill (ZIP download or Claude apps upload)
Download the skill ZIP from this page and unzip it. To make it available to Claude Code for your user account, place the unzipped folder in ~/.claude/skills/. To scope it to one project, place it in that project's .claude/skills/ directory instead.
If you use the Claude apps rather than a terminal, you can upload the ZIP instead. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill there.
- Personal use: unzip into ~/.claude/skills/
- Single project: unzip into your project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
~/.claude/skills/Check the requirements before you start
The skill only works if the machine running the agent has the tools and permissions it depends on. The Google Cloud CLI (gcloud) must be installed and authenticated, and Python 3 must be available to run the helper script. The Policy Simulator API must be enabled on the target project; if it is not, the CLI prompts you to enable it and the agent is instructed to select Yes.
The identity running the commands needs roles/policysimulator.admin, roles/cloudasset.viewer, and an IAM Admin role on the target resource. The skill also writes temporary files to /tmp, so that directory must be writable. Without these, the workflow fails at the simulation or apply step.
- Google Cloud CLI (gcloud), installed and authenticated
- Python 3 to run scripts/analyze_simulation.py
- Policy Simulator API enabled on the target project
- IAM roles: roles/policysimulator.admin, roles/cloudasset.viewer, and an IAM Admin role on the target resource
- Write access to /tmp
Trigger the skill with a natural request
You do not need to type a command name. The skill is meant to be picked up when you ask for a change to IAM v1 allow policies on a project, folder, or organization, especially when you want to simulate or apply it safely. Name the resource and the change you want, and say that you want it checked first.
The skill's description says not to use it for IAM v2 deny policies, VPC Service Controls, or general policy troubleshooting. If you ask for those, expect the skill to be a poor fit.
- "Simulate removing roles/editor from alice@example.com on project my-prod-project before applying it."
- "Safely grant roles/storage.objectViewer to the analytics group on folder 123456789012, and check it against recent access first."
- "Tighten the IAM roles on our organization without breaking running services."
What the agent runs and the safety gates
The skill tells the agent to use only standard public gcloud commands and to tag each gcloud call with a usage attribution variable set inline on that command. The tag identifies the skill and its version and carries no user data. The attribution file says not to use gcloud config set for this, so the label does not persist.
The skill includes two hard stops. If retrieving the policy fails or returns empty JSON, the workflow ends. If the simulator command fails or times out, the agent must not treat that as a safe result and ends the workflow. Read the output of each step rather than assuming success.
- Fetch command for projects: gcloud projects get-iam-policy TARGET_PROJECT_ID --format=json
- Simulation command replays recent access through //cloudresourcemanager.googleapis.com/ resource names
- Apply commands: gcloud projects set-iam-policy, gcloud resource-manager folders set-iam-policy, or gcloud organizations set-iam-policy
- Cleanup removes the three /tmp JSON files whatever the outcome
gcloud iam simulator replay-recent-access //cloudresourcemanager.googleapis.com/projects/TARGET_PROJECT_ID /tmp/proposed_policy.json --project=TARGET_PROJECT_ID --format=json > /tmp/simulation_results.jsonSafety notes: scripts and network use
This skill runs scripts and uses the network. Its helper, scripts/analyze_simulation.py, is run with python3 against /tmp/simulation_results.json, and the gcloud commands call Google Cloud APIs. Because the agent can run real changes to IAM, review the proposed policy and the simulation output yourself before answering Yes.
The simulation has a known limit. It only replays the last 90 days of logs, so access used rarely or not at all may not appear. A SAFE result means no disruption was seen in that window, not a proof that the change is harmless.
- Read /tmp/proposed_policy.json before confirming
- Confirm the target resource ID is the one you intend
- Remember that access older than 90 days is not tested
Tips for getting reliable results
Give the agent the exact resource ID and the exact roles and principals to change. Vague requests make it harder to produce a clean diff between the current and proposed policy. If the agent reports that no change is needed, check that the role or member is actually present or absent as you expected.
Do not expect the skill to replace review. Keep your own change record, and treat a SAFE result as one useful check among others.
- Use the resource type that matches the target: project, folder or organization
- Name one change at a time so any disruption is easy to trace
- If the API prompt appears, confirm it only if you intended to enable the Policy Simulator API
What people use it for
- Removing a broad role such as an editor binding from a user before tightening a production project
- Granting a read-only role to a group on a folder while checking that no current service loses access
- Reviewing role bindings across several projects in an organization before a security audit
- Tidying up service account roles without breaking workloads that still call Google Cloud APIs
Frequently asked questions
How do I install the IAM Policy Simulator Helper skill?
Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings, Capabilities, Skills.
What do I need to run it?
You need the Google Cloud CLI installed and authenticated, Python 3, and the Policy Simulator API enabled on the target project. The identity must hold roles/policysimulator.admin, roles/cloudasset.viewer and an IAM Admin role on the resource.
Is the IAM Policy Simulator Helper free?
The skill is published under the Apache-2.0 licence. The source does not state any price for it, and Google Cloud's own tools such as gcloud are used through your existing account.
Does the simulation guarantee a policy change is safe?
No. The simulator only replays the last 90 days of access logs, so access that is used rarely may not appear. A SAFE result means no disrupted access was found in that window.
Can I use this skill for IAM deny policies or VPC Service Controls?
No. The skill's description says it is for IAM v1 allow policies only and excludes IAM v2 deny policies, VPC Service Controls and general policy troubleshooting. Using it for those gives no useful safety check.
Why does the agent say the change is a no-op?
The skill compares the proposed policy with the current one. If you ask to remove a role the principal does not hold, or add a role they already have, it stops and reports that no change is needed without running a simulation.
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
Use this skill if you administer Google Cloud IAM v1 allow policies and want a repeatable check against recent access logs before every change. Pick something else for IAM deny policies, VPC Service Controls, or general troubleshooting, and do not treat a SAFE result as proof that a rarely used permission is unneeded.
Download the skill