Guide · Agent skill
How to use the TPU Partition Overlap Troubleshooter agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
This guide explains what the TPU Partition Overlap Troubleshooter agent skill does, how to install it for Claude, and how to ask for it in plain language. It is written for engineers who already run TPU workloads on Google Kubernetes Engine (GKE) and see a SliceCreationFailed error. After reading it, you will know how to install the skill, what it checks, and what it will and will not change in your cluster.
TPU Partition Overlap Troubleshootergoogle/skills · Apache-2.0 Download the skill Quick start
- 1Download the ZIP. Download the skill ZIP from this page.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder.
- 3Or upload in the Claude apps. In the Claude apps, open Settings → Capabilities → Skills and upload the skill.
- 4Prepare cluster access. Install gcloud and kubectl with required plugins, enable the required APIs, and confirm the Kubernetes Engine Viewer and Monitoring Viewer roles.
- 5Describe the failure. Ask the agent in plain language, giving the slice name, cluster, and location.
- 6Review the findings. Read the conflicting slice and the linked documentation section, then apply any fix yourself.
What is an agent skill?
An agent skill is a folder that contains a SKILL.md file with instructions and, optionally, reference files. When a skill is installed, an AI agent can read those instructions and follow them for matching tasks. This skill's folder is named gke-ai-troubleshooting-tpu-partition-overlap and includes SKILL.md and references/attribution.md.
What does the skill make the agent do?
The skill handles one failure: a GKE TPU slice that fails to form with the status reason SliceCreationFailed because its requested partitions or nodes are already used by another slice or JobSet. It runs a structured, read-only investigation. The agent confirms the Ready condition reason, rules out the other documented causes, finds the slice that uses the same nodes, and points to the documentation section that describes the fix.
The agent does not apply the fix. The skill's read-only rule says the agent runs only read-only diagnostic commands and never drains, deletes, or re-creates nodes. Any change is left for you to make.
- Confirms that the Ready condition reason is SliceCreationFailed
- Rules out missing nodes and partition-count mismatches
- Identifies the conflicting slice or JobSet
- Links the documentation section that describes the fix
How do you install the skill?
Download the ZIP file for the skill from this page and unzip it. For a personal install, place the folder in ~/.claude/skills/. For a single project, place it in the project's .claude/skills/ folder.
In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/gke-ai-troubleshooting-tpu-partition-overlap/
- Project: .claude/skills/gke-ai-troubleshooting-tpu-partition-overlap/
- Claude apps: Settings → Capabilities → Skills, then upload the skill
What do you need before the skill can work?
The skill cannot troubleshoot without live cluster data, so the environment must be ready first. Its prerequisites are the gcloud CLI, kubectl with the required plugins, a Google Cloud project with active billing, the Google Kubernetes Engine API and Cloud Monitoring API enabled, and network access to Google Cloud and documentation URLs.
The user running the investigation needs the Kubernetes Engine Viewer (roles/container.viewer) and Monitoring Viewer (roles/monitoring.viewer) IAM roles.
- gcloud CLI, initialized with authentication and a project
- kubectl with required plugins and cluster credentials
- Active Cloud Billing account on the project
- Google Kubernetes Engine API (container.googleapis.com) enabled
- Cloud Monitoring API (monitoring.googleapis.com) enabled
- Kubernetes Engine Viewer and Monitoring Viewer roles
How do you trigger the skill with a natural request?
You do not need special syntax. Describe the failure in your own words and include the details you have: the slice name, cluster, location, and project. The skill asks for missing values such as the node pool name or incident time, and it can find some of them itself.
If you are unsure whether this skill applies, paste the Ready condition reason. The skill applies only when the reason is SliceCreationFailed and the cause is node or partition overlap.
What are example requests?
Each example below describes a situation the skill is written for. Replace the placeholders with your own values.
- My slice my-slice in cluster prod-tpu in us-central1 shows SliceCreationFailed. Check whether its partitions are already used by another slice.
- Our TPU slice failed with SliceCreationFailed and I think another JobSet is holding the same nodes. Investigate read-only and tell me which doc section covers the fix.
- Find the slice that uses the same partition IDs as my failed slice and explain the conflict.
What are the safety notes?
The skill's metadata states that it runs no scripts and uses the network. It needs network access to Google Cloud and to documentation URLs. Its commands are read-only by design, and the skill tags gcloud commands it runs in the terminal with a usage attribution variable, set inline on each command rather than saved with gcloud config set.
Because the skill only diagnoses, review any fix it links before you apply it, and check that your IAM roles match what the investigation requires.
- Runs scripts: no
- Uses network: yes
- Read-only: the agent must not change the cluster
- Attribution tag is applied per command, not saved to your gcloud configuration
What tips help the investigation go faster?
Give the slice name and, if you have it, the node pool name and the incident time. Without a node pool name, the skill uses the partition IDs from the slice to find it through Cloud Monitoring. Without an incident time, it uses the Last Transition Time of the Ready condition and searches a 60-minute window around it.
- Keep the Ready condition's Last Transition Time handy
- Record the cluster location as a region or zone
- Ask the agent to cite the documentation section for each fix it suggests
What people use it for
- Finding which JobSet holds the nodes a new TPU slice needs
- Checking partition IDs on a shared TPU node pool before scheduling another slice
- Producing a consistent diagnostic checklist for a platform team triaging slice conflicts
- Gathering the facts to include in a support request
Frequently asked questions
How do I install the TPU Partition Overlap Troubleshooter skill?
Download the 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 upload it under Settings → Capabilities → Skills instead.
What do I need to run this skill?
You need the gcloud CLI, kubectl with required plugins, a Google Cloud project with active billing, the Google Kubernetes Engine and Cloud Monitoring APIs enabled, and the Kubernetes Engine Viewer and Monitoring Viewer IAM roles. Network access to Google Cloud and documentation URLs is also required.
Is this skill free to use?
The source does not state a price or licence cost for the skill itself. The skill's licence is listed as Apache-2.0. Google Cloud resources you use while running the commands are billed under your own project.
Will the skill change my GKE cluster?
No. The skill is written as read-only. It must not drain, delete, or re-create nodes, and it gives any fix to you to apply yourself.
What if my error is quota exhaustion or an unresponsive TPU node?
This skill does not handle those cases. Quota exhaustion, unresponsive TPU nodes, and slice provisioning failures without node overlap are out of scope. For a slice lifecycle or provisioning issue without overlap, the skill points to the gke-ai-troubleshooting-tpu-dynamic-slices-monitoring skill.
How is this different from general GKE troubleshooting?
It focuses on one cause of SliceCreationFailed: requested TPU partitions or their nodes already used by another slice or JobSet. It follows a fixed checklist and links documentation sections for fixes, rather than general cluster diagnosis.
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 run TPU workloads on GKE with dynamic slicing and see SliceCreationFailed errors caused by node or partition overlap, and you want a repeatable read-only checklist. Pick something else if your problem is quota, unresponsive TPU nodes, or general slice provisioning, or if you do not have GKE, gcloud, and kubectl access to a live cluster.
Download the skill