How to use the Agent Platform Troubleshooting agent skill

What is an agent skill and what does this one do?

An agent skill is a folder of instructions and reference files that an AI agent can load when a task matches its description. This skill's SKILL.md file describes when to use it, and its references/ folder holds notes on Agent Gateway, Agent Registry, Agent Identity, a field manual and an attribution file.

When the skill is active and the agent meets an error on the Agent Platform, the agent reads the bundled reference notes and follows the skill's playbook to diagnose the problem. The skill also contains strict pre-flight rules that make the agent refuse some requests, such as generic Compute Engine or Cloud Storage permission questions, and that dictate exact answers for certain registry and Cloud Run scenarios.

Check the requirements before you install

The skill expects you to have a Google Cloud project with Agent Platform resources, and the Google Cloud SDK (gcloud CLI) for the commands it suggests. For curl or REST calls, it expects application default credentials.

• Google Cloud SDK (gcloud CLI) for the commands the skill suggests
• Access to a Google Cloud project with Agent Platform resources
• Application default credentials for curl or REST calls

Install the skill from the ZIP download

Download the ZIP for skills/cloud/agent-platform-troubleshooting from this page, then choose one of the two locations below. Use the personal folder to make the skill available across your projects, or the project folder to limit it to one codebase.

You can also upload the skill in the Claude apps under Settings, then Capabilities, then Skills.

• Personal: unzip into ~/.claude/skills/
• Project: unzip into .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the skill

Trigger the skill with a natural request

You do not need a special command. The skill's description tells the agent to use it when agent requests fail with 403 (especially unauthorized egress), when Agent Runtime queries return 500, or when gateway or IAP logs show permission errors. Describe the symptom and the Agent Platform component in plain words.

• My agent gets a 403 Egress request is not authorized error when calling an MCP server through IAP.
• Agent Runtime queries are returning 500 errors. What should I check first?
• Our gateway logs show permission errors for an agent endpoint. Help me find the cause.
• Walk me through registering a Google API endpoint in Agent Registry.

Know what the skill will refuse

The skill is deliberately narrow. Questions about generic Compute Engine or Cloud Storage access, or general IAM problems unrelated to the Agent Platform, are declined by design. Requests to write or run custom Python or bash discovery scripts are also refused, and the skill points you to standard gcloud CLI commands or curl REST calls instead. For example, the skill suggests gcloud ai reasoning-engines list --region=us-central1 as an alternative.

If you need general IAM or Cloud Storage help, use a different resource rather than this skill.

• Declined: 403 Access Denied when a Compute Engine instance reads a Cloud Storage bucket
• Declined: custom discovery scripts to list all Agent Runtime instances
• Not for: writing your own discovery scripts

Safety notes before you act on its advice

The skill does not run scripts, but it uses the network. Its own guidance recommends creating or updating authorization policies and registry entries, and those changes can affect live traffic and security. Review every proposed change before applying it, especially in production.

The skill also asks the agent to prefix terminal gcloud commands with a usage attribution setting and to add an attribution string to User-Agent headers. Read the attribution reference before running commands, and keep these settings out of generated scripts, Terraform and application code.

• Review AuthorizationPolicy and registry changes before applying them in production
• Commands run in the terminal are prefixed for attribution; generated code is not
• Expect the skill to refuse some requests by design

Tips for getting useful results

Give the agent the exact error text, the component involved (Agent Gateway, Agent Registry, Agent Identity, Model Armor or IAP), and the region if you know it. These details let the agent match the case to the right reference file.

Ask for the diagnosis before asking for changes. The skill's Telemetry guidance and IAP guidance both push toward a specific sequence of checks, so following that order is usually faster than jumping to a fix.

• Paste the full error message and the request path
• Name the component: Agent Gateway, Registry, Identity, Policies, Model Armor or IAP
• Check IAP Egressor bindings on the registry entry first, as the skill's IAP guidance prioritises this