Skip to content
Get packs

Troubleshoot GKE TPU VMs in Repair

Diagnose GKE TPU VMs stuck in Compute Engine REPAIRING state using read-only checks

Source Download skill
Repository
google/skills
Stars
21,782
Licence
Apache-2.0
Files
2 files

What it does

When installed, the agent gets a step-by-step troubleshooting guide for Google Kubernetes Engine (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, and then points the user to the relevant Google documentation for fixes rather than changing the cluster itself. It also routes users to other skills when the problem is actually a different node or pod issue.

Great for

  • Platform or ML engineers running TPU slice node pools on GKE who see workloads unschedulable
  • Site reliability engineers investigating host errors or maintenance events in audit logs
  • Teams using multi-host, dynamic slicing, or TPU All Capacity mode node pools

Skip it if

  • Nodes showing Ready: Unknown or other NotReady states without any VM in REPAIRING; the skill says to use other troubleshooting skills for those
  • Anyone not running GKE TPU workloads, since the guidance is specific to that setup and would not apply
  • Users expecting the agent to apply the fix automatically; the skill forbids changing the cluster and leaves fixes to the user

Try asking

  • “My TPU slice node pool has instances stuck in REPAIRING, help me find out why”
  • “Check the audit logs for host error events on my GKE TPU VMs”
  • “Why are my TPU slices unschedulable even though the nodes look healthy?”
Step-by-step guide: how to use Troubleshoot GKE TPU VMs in RepairInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 2 original files, the Apache-2.0 licence and an attribution note.

    gke-ai-troubleshooting-tpu-vm-repair-stuck.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip gke-ai-troubleshooting-tpu-vm-repair-stuck.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip gke-ai-troubleshooting-tpu-vm-repair-stuck.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Make sure gcloud and kubectl are authenticated to the right project and cluster before starting, since the skill depends on those credentials.
  • Ask the agent to link the documentation section for any recommended fix, then apply the fix yourself after reviewing it.
  • Provide the node pool name and cluster name up front to speed up the context-collection step.

What's inside

  • references/attribution.md
  • SKILL.md

Redistributed unmodified from google/skills under the Apache-2.0 licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.