How to use the Troubleshoot GKE TPU VMs in Repair agent skill

What the skill makes the agent do

When installed, the agent gets a step-by-step troubleshooting guide for GKE TPU machines that are stuck in a REPAIRING state after hardware host errors, maintenance events, or faulty host reports. The agent checks the VM status, host events in audit logs, and GKE repair status, using read-only commands only.

• Checks the VM status of the TPU instances in the affected node pool.
• Reads host events in Cloud Audit Logs.
• Checks GKE repair status.
• Points you to the relevant Google documentation for fixes.
• Routes you to other skills when the problem is a different node or pod issue.

Install the skill from the ZIP file

Download the ZIP file for the skill from this page and unzip it. Agent skills are folders containing a SKILL.md file and supporting files. The skill folder is named gke-ai-troubleshooting-tpu-vm-repair-stuck and contains SKILL.md and references/attribution.md.

For a personal install that works in every project, unzip the folder into ~/.claude/skills/. To limit it to one project, unzip it into that project's .claude/skills/ folder instead.

If you use the Claude apps rather than a terminal, upload the skill under Settings → Capabilities → Skills.

Trigger the skill with a natural request

You do not need to type the skill name. The agent loads the skill when your request matches its description. The skill is designed for cases where TPU instances in a slice node pool remain in REPAIRING, host error events appear in audit logs, or TPU slices are unschedulable because a VM is in repair.

Describe the symptom in plain words and include your cluster details if you have them, such as the project, cluster, location, and node pool name.

• My TPU slice node pool has a VM stuck in REPAIRING after a host error. Can you check it?
• Our multi-host TPU workloads are unschedulable and I see host error events in the audit logs.
• Some TPU instances in our All Capacity mode node pool have been repairing for hours. What is going on?

What to provide the agent

The agent first collects context before running any checks. It needs the project ID, cluster name, cluster location, cluster mode (Autopilot or Standard), TPU version, and the TPU node pool name. For Standard clusters it reads the node pool's instance group details. For Autopilot clusters, or when the node pool name is unknown, it uses the MIG listing steps from the Google documentation.

• {project_id}, {cluster_name}, {location}, {cluster_mode}, {tpu_version}, {nodepool_name}
• Whether the node pool is single-host or multi-host

Safety: scripts, network and permissions

This skill runs scripts and uses the network. It runs read-only diagnostic commands and is forbidden from draining, deleting, re-creating nodes, or running any other command that changes the cluster. Fixes are given to you to apply yourself.

Every gcloud command the agent runs is tagged with an attribution environment variable that identifies the skill and its version. The tag contains no user data, and the skill says not to use gcloud config set for it so the tag does not persist.

• Required IAM roles: Kubernetes Engine Viewer, Compute Viewer, and Logs Viewer.
• Cluster Admin is only needed by the user who enables node auto-repair.
• The project needs active billing and the Kubernetes Engine, Compute Engine, and Cloud Logging APIs enabled.
• Required tools: the gcloud CLI and kubectl with its required plugins.

Tips for getting useful results

Have your tools and access ready before you start, so the agent's checks are not blocked. Use the skill for the specific symptom it covers. If your nodes show Ready: Unknown and no VM is in REPAIRING, the skill directs you to other troubleshooting skills instead.

• Confirm gcloud and kubectl work for your project before asking.
• Keep the node pool name handy; it saves a discovery step.
• If the agent recommends a fix, follow the linked documentation section it cites.