Skip to content
Get packs

Guide · Agent skill

How to use the GKE HPA Scaling Troubleshooter 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 HPA Scaling Troubleshooter, an agent skill named gke-workload-scaling-troubleshooting, which helps an AI agent diagnose why a HorizontalPodAutoscaler on Google Kubernetes Engine is not scaling a workload as expected. It is aimed at platform engineers, DevOps staff and developers who have access to a GKE cluster. By the end you will know what the skill does, how to add it to your agent, how to ask for help in plain language, and what it needs to run.

GKE HPA Scaling Troubleshootergoogle/skills · Apache-2.0

Quick start

  1. 1Download and unzip the skill. Download the ZIP from this page and unzip it so that SKILL.md sits inside a folder named for the skill.
  2. 2Place it where your agent looks. Move the folder into ~/.claude/skills/ for personal use or into .claude/skills/ in a project, or upload it under Settings → Capabilities → Skills in the Claude apps.
  3. 3Prepare cluster access. Install gcloud and kubectl, then fetch credentials with gcloud container clusters get-credentials for your cluster.
  4. 4Describe the problem. Tell the agent the HPA name, namespace, cluster and what you observe, such as unknown metrics or no scaling under load.
  5. 5Let the agent run the read-only checks. The agent runs kubectl describe hpa and reads the Metrics, Conditions and Events, and may query Cloud Logging for historical events.
  6. 6Review the proposed correction. Check the matched failure pattern and the suggested configuration change before applying it through your normal review process.

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

An agent skill is a folder containing a SKILL.md file and any supporting files. When it is installed, an AI agent that supports skills can load its instructions and follow them when a request matches the skill's description. This skill covers HorizontalPodAutoscaler (HPA) failures on GKE: metrics showing as <unknown>, FailedGet* events, missing Pod resource requests, broken custom or external metrics pipelines, HPAs that will not scale up or down, scale-to-zero problems, and slow HPA reaction on large clusters.

The agent first runs kubectl describe hpa, reads the Metrics, Conditions and Events sections, and matches the signal to one of six troubleshooting branches. It then proposes a specific correction, packaged as a configuration change you can review. The skill is designed to be read-only during diagnosis.

  • Reads HPA status and events, both live and from Cloud Logging for historical events.
  • Matches errors such as FailedGetScale, FailedComputeMetricsReplicas, FailedGetResourceMetric and FailedGetExternalMetric to a known cause.
  • Recommends a correction as a reviewable GitOps change rather than applying it directly.
  • If the cluster cannot be reached, it gives you the exact kubectl and gcloud commands to run yourself.

Install the skill with a ZIP download or the Claude apps

Download the skill's ZIP file from this page and unzip it. For a personal setup, place the unzipped folder inside ~/.claude/skills/. For a single project, place it inside that project's .claude/skills/ folder. Either way, the folder should contain SKILL.md and the references folder.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

  • Personal install: ~/.claude/skills/
  • Project install: .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills

Trigger the skill with a natural request

You do not need a special command. Describe the problem in plain words and name the HPA or workload if you know it. The skill's description covers requests about HPAs that are not scaling or that report metric errors. Mention the namespace if it is not default, because the skill assumes default when none is given.

Requests that match well include an HPA showing unknown metrics, an app that does not scale under load, or an error event you have copied from kubectl. Requests about writing new HPA or VPA objects, or about scaling best practices, belong to the separate gke-workload-scaling skill.

  • "My HPA web-frontend in namespace shop shows <unknown> for its CPU metric. Why?"
  • "The orders deployment isn't scaling up under load. Here is the output of kubectl describe hpa orders."
  • "Our custom metrics HPA logs FailedGetCustomMetric. Help me find the cause."
  • "Check the HPA for worker in project my-project, cluster prod-cluster, europe-west1."
kubectl describe hpa {hpa_name} -n {workload_namespace} kubectl get hpa {hpa_name} -n {workload_namespace} -o yaml

What you need before you start

The most useful diagnosis needs live cluster access. The skill expects the gcloud CLI and kubectl. To read live data, you need access to the GKE cluster, with credentials fetched using gcloud container clusters get-credentials. If you cannot get access, the skill switches to a fallback mode and you run the commands it lists.

For historical HPA events, you need read access to Cloud Logging. The skill is not meant for beginners without cluster access, because most of its steps depend on live cluster data.

  • gcloud CLI
  • kubectl
  • Access to the GKE cluster for live diagnosis, or willingness to run the listed commands manually
  • Read access to Cloud Logging for historical events
gcloud container clusters get-credentials {cluster_name} --location {cluster_location} --project {project_id}

Safety notes: scripts and network use

This skill runs scripts and uses the network. Its commands call Google Cloud and the Kubernetes API, so a cluster and gcloud credentials are used during diagnosis. The skill's guidance says to prefix gcloud commands run directly in the terminal with a usage attribution variable, and to avoid setting it persistently with gcloud config set. That tag identifies only the skill and its version.

Diagnosis is read-only by design, and changes are proposed as reviewable configuration rather than applied on your behalf. Review every proposed manifest before you apply it to a cluster, and check the commands the agent runs before approving them.

  • The skill runs scripts and uses the network, so review what the agent executes.
  • Diagnosis is read-only; corrections are proposed as reviewable configuration.
  • Gcloud attribution is set inline per command, not stored in your configuration.

Tips for better results

Give the agent the exact output of kubectl describe hpa, including the Metrics, Conditions and Events sections. Event names such as FailedGetResourceMetric narrow the search quickly. If an event has rolled off the live list, ask for a Cloud Logging check on HorizontalPodAutoscaler events.

If the symptom is slow scaling on a cluster with many HPA objects, say so, since the skill has a separate branch for that. Cluster Autoscaler and node-pool sizing problems are outside its scope.

  • Paste the full describe output rather than a summary.
  • Name the cluster, location, project and namespace up front.
  • Ask for the commands to run if you have no cluster access.

What people use it for

  • Diagnosing an HPA that shows <unknown> for a CPU or memory metric after a Pod spec change.
  • Finding why a deployment does not scale up under load because containers lack resource requests.
  • Tracing FailedGetExternalMetric or FailedGetCustomMetric errors back to an unavailable metrics adapter.
  • Checking whether two HPAs target the same workload and fight over the replica count.

Frequently asked questions

How do I install the GKE HPA troubleshooting 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. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.

What do I need to use this skill?

You need the gcloud CLI and kubectl. For live diagnosis you also need access to the GKE cluster, with credentials from gcloud container clusters get-credentials. Read access to Cloud Logging is needed for historical HPA events.

Is the skill free to use?

The skill is licensed under Apache-2.0, as stated on this page. Check the licence file in the source repository for the full terms.

Can the skill fix my HPA automatically?

Diagnosis is designed to be read-only. The skill proposes a specific correction as a reviewable configuration change, which you review and apply through your own process.

What if the agent cannot connect to my cluster?

The skill switches to a fallback mode and lists the exact kubectl and gcloud commands for you to run. It then works from the output you share.

Does this skill write new HPA or VPA configurations?

No. Creating new HPA or VPA objects and scaling best practices are covered by the separate gke-workload-scaling skill. This one focuses on diagnosing failures.

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 platform or DevOps engineers and developers who have GKE cluster access and see HPA metric errors or scaling that does not behave as expected. It is not a good choice for writing new autoscaling configuration, for Cluster Autoscaler or node-pool problems, or for anyone without cluster access who wants a hands-on tool.

Download the skill