Guide · Agent skill
How to use the GKE Node NotReady Troubleshooter agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The GKE Node NotReady Troubleshooter is an agent skill, a packaged set of instructions that an AI agent such as Claude loads when a task matches it. It is for platform or SRE engineers, and developers who see pods evicted or stuck Pending, when a Google Kubernetes Engine node shows NotReady or Unknown status. After this guide you will know how to install the skill, how to phrase a request so the agent uses it, and what the agent will check and propose.
GKE Node NotReady Troubleshootergoogle/skills · Apache-2.0 Download the skill Quick start
- 1Download the ZIP. Download the gke-node-notready 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. Open Settings → Capabilities → Skills and upload the skill.
- 4Check the prerequisites. Make sure gcloud can reach the target project, kubectl has cluster credentials, and you have Cloud Logging read access.
- 5Describe the NotReady symptom. Ask in plain language, including the project, cluster, location and node name if you have them.
- 6Review the findings. Read the root-cause mapping and the proposed remediation commands before running anything.
What the skill makes the agent do
When a GKE node reports NotReady or Unknown, the skill guides the agent through a structured investigation. It checks node conditions and events, scans kubelet and containerd logs, and reviews node metrics. It maps the error patterns it finds to likely root causes such as container runtime failures, memory or disk pressure, or networking problems.
The skill is designed to be read-only. It proposes remediation commands for a person to review and run, and it does not change the cluster itself. It also tells the agent to rule out an expected NotReady first, such as a node that is still provisioning, upgrading, being repaired, cordoned, or scaling down.
- Checks node Conditions and Events with kubectl and Cloud Logging
- Scans kubelet logs and serial-console output for known error signatures
- Reviews node metrics such as memory, CPU and ephemeral storage usage
- Proposes fixes for a human to apply; it never drains, deletes or recreates nodes automatically
Install the skill from the ZIP or the Claude apps
Download the ZIP for gke-node-notready from our page and unzip it. For a personal setup, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.
If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal: unzip into ~/.claude/skills/
- Project only: unzip into the project's .claude/skills/
- Claude apps: Settings → Capabilities → Skills, then upload
Trigger the skill with natural requests
You do not need to name the skill. The skill description says it applies when nodes show NotReady, when the kubelet stops posting node status, or when workloads are evicted or stuck Pending due to node health. Describe the symptom and give the details the agent needs: the cluster name, its location, the project, and the node name if you have it.
The agent first looks for these values in your prompt, in active settings, or in environment defaults such as the current kubectl context and the gcloud project. If it cannot reach the cluster, it presents the exact commands for you to run and continues from the symptoms you report.
- "Node gke-prod-pool-1-abc123 in cluster prod-east is NotReady in project acme-prod, location us-central1. Why?"
- "Pods on our GKE nodes were evicted this morning. Check whether node health caused it."
- "Some nodes in cluster staging-1 went Unknown around 14:00 UTC. Investigate."
What the agent checks, step by step
The agent starts with kubectl get nodes -o wide and kubectl describe node for the affected node. It sets a one-hour time window centred on the issue time, from 30 minutes before to 30 minutes after, and uses it for all log and metric queries. For history, it can open Logs Explorer queries for node events and kubelet warnings.
Based on the signatures it finds, the agent follows a branch: container runtime, resource pressure and OOM, PLEG health, networking, admission webhooks, or lease termination. If the cause is still unclear, it widens the search and suggests escalation.
- Conditions: Ready False or Unknown, MemoryPressure, DiskPressure, PIDPressure, NetworkUnavailable
- Kubelet log warnings and serial-console kernel messages such as OOM-killer or TaskHung
- Signatures such as runtime is down, PLEG is not healthy, and NetworkPluginNotReady
kubectl get nodes -o wide
kubectl describe node "{node_name}"Safety notes: scripts and network access
The skill declares that it runs scripts and uses the network. Its requirements are the gcloud CLI with access to the target Google Cloud project, kubectl with credentials for the GKE cluster, and Cloud Logging read access for Logs Explorer queries. Review what the agent runs before you approve it, and use an account with the least access that still lets it read the cluster.
Before running gcloud commands, the skill requires the agent to read its usage attribution file. For commands run directly in a terminal, the agent prefixes gcloud with a CLOUDSDK_METRICS_REQUEST_ATTRIBUTION value that names the skill and version, and it does not use gcloud config set for this. The tag carries no user data.
- Requires gcloud, kubectl credentials and Cloud Logging read access
- Runs scripts and uses the network
- Remediation commands are proposals; a person must review and run them
Tips for better results
Give the agent the exact node name and cluster location when you have them, because the skill's first step depends on those values. If you only have a symptom, say so and the agent will work from it.
Do not use the skill for application bugs or autoscaler questions. The skill redirects those to other skills: gke-workload-troubleshooting for pod-level application failures and gke-cluster-autoscaler for scale-up or scale-down decisions.
- Provide project, cluster, location and node name in the first message
- State the time the problem started so the one-hour window is accurate
- Keep the read-only boundary: review every proposed command before running it
What people use it for
- Diagnosing a node that flips between Ready and NotReady in a production GKE cluster
- Finding out why pods were evicted or stuck Pending after a node health problem
- Checking a node for memory, disk or PID pressure before changing machine types or disk sizes
- Getting a consistent, read-only first pass before a platform team makes cluster changes
Frequently asked questions
How do I install the gke-node-notready agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. If you use the Claude apps, you can upload it under Settings → Capabilities → Skills instead.
What do I need to use this skill?
You need the gcloud CLI with access to the target Google Cloud project, kubectl with credentials for the GKE cluster, and Cloud Logging read access for Logs Explorer queries. The skill runs scripts and uses the network.
Is the GKE Node NotReady skill free?
The skill is published under the Apache-2.0 licence. This page does not state pricing for Google Cloud resources, which you pay for separately as you use them.
Will the skill change my cluster?
No. The skill is designed to be read-only. It gathers evidence and proposes kubectl or gcloud commands for a person to review and run. It never drains, deletes or recreates nodes automatically.
Does this skill work for pod application bugs or autoscaling?
No. Pod-level application failures belong to gke-workload-troubleshooting, and autoscaler scale-up or scale-down decisions belong to gke-cluster-autoscaler. The skill also does not cover non-GKE compute such as other Kubernetes distributions or plain virtual machines.
Why does my agent say the node is expected to be NotReady?
A node that is newly provisioning, upgrading, being repaired, cordoned, or scaling down can report NotReady briefly. The skill checks for this first and only treats it as a fault if the status persists beyond the expected window.
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 GKE clusters and want an agent to run a structured, read-only first pass on NotReady nodes before anyone changes the cluster. Pick something else if your problem is application code inside pods, autoscaler behaviour, or a Kubernetes distribution other than GKE.
Download the skill