Guide · Agent skill
How to use the GKE Workload Troubleshooting agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The GKE Workload Troubleshooting skill is an agent skill that guides an AI agent through diagnosing applications that fail on Google Kubernetes Engine (GKE). It covers pods that crash, won't start, or can't pull their container image, and it follows a fixed checklist of pod status, events and logs before proposing a root cause. After this guide you will know what the skill does, how to install it from a ZIP file, how to ask for it in plain language, and what to check before you act on its suggestions.
GKE Workload Troubleshootinggoogle/skills · Apache-2.0 Download the skill Quick start
- 1Download the ZIP file. Get the skill's ZIP file from its page on this site. Keep the file as it was downloaded.
- 2Unzip into a skills folder. Unzip the file into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project folder to limit it to that project.
- 3Or upload it in the Claude apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP file.
- 4Describe the failure. Ask for help in plain language, naming the workload, namespace, status such as CrashLoopBackOff, and any error text you have.
- 5Check the diagnosis and commands. Read the root cause and proposed fix. Run any kubectl commands it lists yourself to confirm the findings.
- 6Apply and verify fixes yourself. The skill only proposes changes. Apply a manifest or IAM change through your normal process and verify that the workload recovers.
What does the GKE Workload Troubleshooting skill make the agent do?
An agent skill is a folder of instructions and optional scripts that an AI agent loads when a task matches the skill's description. This one is for application workloads running in GKE clusters that keep crashing, fail to start, or cannot pull their container image.
The skill makes the agent work through a structured checklist: it checks pod status, reads events and logs, and works out the likely root cause. It then proposes a fix, such as a Kubernetes manifest change or an IAM adjustment, and explains why. The skill is designed not to change live systems itself. A person needs to apply and verify any change.
- Recognises statuses such as CrashLoopBackOff, OOMKilled, ImagePullBackOff, Pending and ContainerCreating
- Reads the pod's terminated reason and exit code to narrow down the cause
- Queries Kubernetes events and Cloud Logging for the time window around the failure
- Proposes manifest or Google Cloud fixes and explains them
- If the cluster can't be reached, lists the kubectl commands to run and still drafts a likely fix from the symptoms you describe
Install the skill from the ZIP file or the Claude apps
You can install the skill in one of two ways. Choose the one that matches how you use your agent. Both start from the skill's page on this site, where you download the ZIP file.
For a personal setup, unzip the downloaded file into your skills folder at ~/.claude/skills/. To make the skill available only inside one project, unzip it into the .claude/skills/ folder of that project instead. The skill folder includes SKILL.md, which holds the instructions, and a references folder with an attribution file.
If you use the Claude apps, you can upload the ZIP there instead. Open Settings, go to Capabilities, then Skills, and upload the file.
- Personal use: unzip into ~/.claude/skills/
- Single project: unzip into .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
How do you trigger the skill with a natural request?
You do not need to type a command to start the skill. Describe the failure in plain language and include the details you have. The skill's description tells the agent to use it when pods fail to start or crash repeatedly, so a request that names a symptom is usually enough.
The skill fills in missing details itself. The workload namespace defaults to default if you don't give one. The agent also looks at your active kubectl context and gcloud project. If you give a time, such as 'five minutes ago', it centres a one-hour search window on that time. If you give no time, it uses the current time.
- 'My checkout deployment in the shop namespace is stuck in CrashLoopBackOff. Find out why.'
- 'Pods for the reports-api workload show OOMKilled after the last release. What is the likely cause?'
- 'Pods are stuck in ImagePullBackOff in project my-project. Diagnose it and suggest a fix.'
- 'Something is wrong with my GKE workload from about 20 minutes ago. Here is the error message.'
- 'I have no access to the cluster. Give me the kubectl commands to run and draft a fix from these symptoms.'
What checks does the agent run first?
The agent starts by finding the deployment's selector labels, then lists the matching pods and their status. Its next step depends on what it finds. For a Pending pod, it goes straight to the namespace events. For CrashLoopBackOff, it reads the terminated reason and exit code before looking at logs. For ImagePullBackOff, it reads the exact pull error from the events.
The exit code points to different causes. Exit code 137 with reason OOMKilled means the container hit its memory limit. Exit code 0 is unexpected for a long-running Deployment, because the restart policy restarts a process that finished. Exit code 128 means the command or entrypoint path is wrong or missing from the image. Exit code 1 or another non-zero code means the application crashed, for example from bad configuration, missing environment variables, unreachable dependencies, or authentication errors (401 or 403) on Google Cloud calls.
- Pending: the pod cannot schedule on any node; check events for FailedScheduling
- ImagePullBackOff or ErrImagePull: read the pull error in the events
- ContainerCreating: the container is blocked by a volume mount, networking or an image pull
- A healthy exit code that still restarts can mean a liveness probe failure
kubectl get deployment {workload_name} -n {workload_namespace} -o jsonpath='{.spec.selector.matchLabels}'
kubectl get pods -l {selector_labels} -n {workload_namespace}
kubectl describe pod {pod_name} -n {workload_namespace}
kubectl get pod {pod_name} -n {workload_namespace} -o jsonpath='{.status.containerStatuses[*].lastState.terminated}'What does the skill need to run?
The skill expects two command-line tools. The gcloud CLI is used to fetch cluster credentials and to query Cloud Logging. kubectl is used to inspect pods, deployments and events. You also need access to the target GKE cluster and project. If you cannot reach the cluster, the skill can still work from the symptoms you describe, but it will give you commands to run rather than live results.
The skill runs scripts and uses the network, so review what it will execute in your environment before you run it on a work machine.
- gcloud CLI: cluster credentials and Cloud Logging queries
- kubectl: pod, deployment and event inspection
- Access to the target GKE cluster and project, or the reported symptoms if running offline
- Runs scripts: yes
- Uses network: yes
What safety rules should you know about?
The skill works under a read-only diagnostics boundary. It proposes fixes, whether Kubernetes manifest patches or Google Cloud changes such as IAM bindings or node pool recreation, but it does not execute live changes itself. Treat every proposal as a draft that a person must review, apply and verify.
The skill also asks the agent to tag its gcloud commands with an attribution value so that usage can be traced to the skill. The attribution file says the tag is set inline on each command and is not saved with gcloud config set. Do not use this skill for production incidents without human review of the proposed fix.
- The skill only proposes changes; a human must apply and verify them
- It is not for provisioning clusters or creating node pools
- It is not for non-Kubernetes Google Cloud services
- Gcloud commands run in the terminal carry an inline attribution setting; generated scripts, Terraform and user code do not
Tips for getting better results
Give the agent as much context as you can: the workload name, namespace, cluster name and location, and the exact error text. Include the time the failure started if you know it, because the skill searches events around that time. Paste the output of kubectl describe or the last terminated state if you already have it, so the agent can skip ahead.
If the cluster is unreachable, ask for the runbook first. You can run the listed kubectl commands yourself and then paste the results back into the conversation for a more specific diagnosis.
- Name the namespace; otherwise the agent assumes default
- Include the exact status (for example OOMKilled) and any error message
- Give a time window when the failure was not happening right now
- Ask for the commands alone when you want to run the checks yourself
What people use it for
- Finding out why a newly deployed service keeps restarting with CrashLoopBackOff
- Checking whether OOMKilled pods need a higher memory limit or have a container-level problem
- Reading the pull error behind ImagePullBackOff to see whether the image name, registry or permissions are wrong
- Getting a first-pass diagnosis and a kubectl runbook for a cluster you cannot reach from your current machine
Frequently asked questions
How do I install the GKE Workload Troubleshooting skill?
Download the ZIP file from the skill's page on this site and unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. In the Claude apps, you can instead upload the ZIP under Settings, then Capabilities, then Skills.
Is the GKE Workload Troubleshooting skill free?
The skill is published under the Apache-2.0 licence. This page does not state pricing for the Claude apps or any other product you may use with it, so check those services for their own costs.
What do I need before the skill works?
You need the gcloud CLI for cluster credentials and Cloud Logging queries, and kubectl for inspecting pods, deployments and events. You also need access to the target cluster and project, or you can describe the symptoms if you are working offline.
Does the skill change my cluster automatically?
No. The skill is designed to read and diagnose, and it only proposes manifest or Google Cloud changes. A person must apply and verify those changes.
What should I do if the cluster is unreachable?
The skill switches to a fallback mode. It lists the exact kubectl commands for you to run and drafts a likely fix from the symptoms you describe, without needing live access.
Which problems is this skill not meant for?
It is not for provisioning GKE clusters or creating node pools, and it is not for problems with non-Kubernetes Google Cloud services. Treat it as a first-pass diagnosis tool rather than a replacement for review during production incidents.
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 are a developer or platform engineer who regularly sees CrashLoopBackOff, OOMKilled, ImagePullBackOff or Pending pods and wants a consistent first-pass diagnosis with a clear runbook. Pick something else for cluster provisioning, node pool creation or non-Kubernetes Google Cloud problems, and do not apply its proposals to a production system without a human review.
Download the skill