Skip to content
Get packs

Guide · Agent skill

How to use the GKE TPU Dynamic Slices Monitoring agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

This guide explains how to install and use the GKE TPU Dynamic Slices Monitoring skill, an agent skill that teaches an AI agent to inspect TPU slices (groups of Google's AI accelerator chips) running on Google Kubernetes Engine (GKE). It is written for engineers and platform teams who run TPU workloads and want faster diagnosis of slice problems, and who may never have used an agent skill before. By the end you will know how to install the skill, phrase requests that trigger it, and what safety checks the agent applies before changing anything.

GKE TPU Dynamic Slices Monitoringgoogle/skills · Apache-2.0

Quick start

  1. 1Download and unzip the skill. Download the skill ZIP from this page and unzip it to get the skill folder containing SKILL.md.
  2. 2Place it in your skills folder. Move the folder to ~/.claude/skills/ for personal use or to .claude/skills/ in a project. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills instead.
  3. 3Confirm cluster access. Make sure kubectl and gcloud are configured for your GKE cluster and project, and that Cloud Logging is enabled.
  4. 4Describe the problem. Ask the agent in plain language, giving the slice name and, if known, project, cluster and location.
  5. 5Review the diagnosis. Check the state explanation and recommended action the agent gives, and the checklist results for provisioning failures.
  6. 6Confirm any high-risk step. For finalizer removal or controller disabling, read the proposed command and warning, then confirm only if you understand the consequences.

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

An agent skill is a folder containing a SKILL.md file and supporting files that an AI agent loads when a task matches the skill's description. This skill covers TPU Dynamic Slices custom resources on GKE. When you ask about a slice's status, it runs kubectl describe on the slice and reads its Status.Conditions against a lookup table of lifecycle states and reasons, then explains the state and suggests next steps.

  • Explains states such as ACTIVATING, ACTIVE, ACTIVE_DEGRADED, FAILED, DEACTIVATING and INCOMPLETE, with a recommended action for each.
  • Walks through provisioning failure checks: node existence and allocation, topology alignment, and reservation block alignment.
  • Checks single-slice and multi-slice (JobSet) workload manifests for the required TPU annotations and nodeSelector labels.
  • Guides removal of stuck finalizers to force-delete a hung slice, with a warning that this can leave cloud resources orphaned.
  • Covers disabling the slice controller and deleting the slice CRD, both marked high risk.

Install the skill in Claude Code or the Claude apps

Download the skill ZIP from this page and unzip it. For Claude Code, place the unzipped skill folder in ~/.claude/skills/ to make it available for all your projects, or in a project's .claude/skills/ folder to limit it to that project.

In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

  • Personal install: ~/.claude/skills/
  • Project install: .claude/skills/ inside your project directory

Set up the prerequisites before you start

The skill depends on existing cluster access. It does not create clusters. Confirm the following before asking the agent to work on a slice.

  • Cloud Logging is enabled for your Google Cloud project.
  • The kubectl CLI is configured to access the GKE cluster.
  • The gcloud CLI is configured with access to the project.
  • Your Kubernetes access allows you to describe, get and patch slice custom resources.

Trigger the skill with natural requests

You do not need to name the skill. Describe the problem in plain language, and include the slice name and, if you have them, the project, cluster and location. The skill's Step 0 asks for these values, and defaults the issue time window to 30 minutes either side of the time of the problem if you do not give one.

  • "Check the status of slice test-slice on my TPU cluster."
  • "My TPU slice has been in SliceCreationFailed for ten minutes. Why?"
  • "Is my JobSet manifest set up correctly for multi-slice TPU training?"
  • "The slice tpu-slice-1 is stuck in DEACTIVATING. What are my options?"
  • "Help me disable dynamic slicing on cluster tpu-cluster."

Read the output and act on it

For a status question, the agent runs kubectl describe slice with the name you give and matches the Ready condition's Reason and Status against the lookup table. For a failed provisioning, it works through the checklist: confirm nodes exist and are unallocated, confirm the partition count matches the topology (for example, topology 2x2 requires 4 nodes), and confirm all nodes share a reservation block.

For manifests, the skill checks the Pod template for the slice topology annotation and the topology, accelerator and slice nodeSelector labels. For multi-slice JobSets, it checks the exclusive-topology annotation and warns against setting the slice label manually, because JobSet assigns it.

kubectl describe slice test-slice

Understand the high-risk operations

Two operations are marked high risk in the skill. The first is removing finalizers from a stuck slice. The skill proposes a JSON patch on /metadata/finalizers, warns that this bypasses normal controller dismantling and can leave VM, network or accelerator resources orphaned, and must ask you to confirm before it applies the patch. The second is disabling the slice controller and deleting the slice CRD, which the skill says to do only after all slices are deleted.

Review these with someone who understands the cluster before confirming. The agent is instructed to pause for your confirmation, so do not approve a patch you have not read.

  • Do not approve a finalizer patch while the slice still has working resources you need to keep.
  • Check kubectl get slice -A before disabling the controller.
kubectl patch slice test-slice --type json -p='[{"op": "remove", "path": "/metadata/finalizers"}]'

Safety, scripts and network use

The skill runs scripts and uses the network. Its attribution reference asks the agent to tag gcloud commands run in the terminal with a metrics environment variable that identifies only the skill and its version. The skill's own description says it carries no user data. The attribution tag is applied to direct terminal commands, not to generated scripts, Terraform or user code. Review the files in the ZIP, including scripts/validate_queries.sh, before running the skill in a sensitive environment.

  • Files included: SKILL.md, references/attribution.md, references/failure_signatures.md, scripts/validate_queries.sh.
  • The failure_signatures.md file contains example conditions for FAILED and SliceCreationFailed to help the agent recognize patterns.
  • Use a cluster and project where you have the access you need, and avoid running high-risk operations in production without review.

What people use it for

  • Diagnosing why a TPU slice is in SliceCreationFailed or FAILED and which nodes or reservation block to check.
  • Checking that a multi-slice JobSet training manifest has the exclusive-topology annotation and correct TPU labels before deployment.
  • Confirming whether a slice in ACTIVE_DEGRADED needs node VM inspection or workload log review.
  • Working through a stuck DEACTIVATING slice with a guided checklist before patching finalizers.

Frequently asked questions

How do I install the GKE TPU Dynamic Slices agent skill?

Download the skill ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ for all projects or in a project's .claude/skills/ folder for one project. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

What do I need before using this skill?

You need Cloud Logging enabled for the project, kubectl and gcloud configured to access your GKE cluster, and Kubernetes access to describe, get and patch slice resources. The skill depends on an existing cluster and does not create one.

Is this skill free to use?

The skill is licensed under Apache-2.0, as listed on this page. Google Cloud and GKE usage is billed separately under your own account, and this page does not state any prices.

Can this skill create a GKE cluster or node pool?

No. The skill says generic GKE node pool creation and non-TPU workloads should be handled by gke-basics or gke-cluster-creation instead.

Is it safe to remove finalizers from a stuck slice with this skill?

The skill warns that removing finalizers bypasses standard controller cleanup and may leave VM, network or accelerator resources orphaned. It requires explicit confirmation before applying the patch, and you should have someone familiar with the cluster review it first.

Why does the agent say my JobSet should not set the slice label?

The skill's guidance says not to specify cloud.google.com/gke-tpu-slice manually in a JobSet's nodeSelector, because JobSet handles slice assignment automatically.

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

This skill suits engineers and SRE or platform teams who run TPU training or inference on GKE and want a structured way to read slice status, check manifests and approach stuck resources. Skip it if you do not have an existing GKE TPU cluster, or if you need general GKE node pool creation or non-TPU workload help, where the skill itself points you to gke-basics or gke-cluster-creation.

Download the skill