How to use the GKE Workload Scaling agent skill

What the skill makes the agent do

Agent skills are folders of instructions and templates that an agent loads when a task matches their description. With this skill installed, the agent follows built-in workflows for scaling applications on GKE: scaling a deployment to a fixed number of replicas, setting up HPA to scale on observed CPU or memory utilization or custom metrics, and setting up VPA to match pod resource requests to actual usage.

The skill also covers rightsizing. The agent can compare VPA recommendations against current requests and suggest new values with a 20% buffer. It flags common pitfalls, such as configuring HPA and VPA on the same metric, which the skill says causes thrashing, and running VPA in Auto mode without graceful shutdown handling.

Install the gke-workload-scaling skill

You can install the skill in one of three ways. Download the ZIP from the skill's page on this directory and unzip it into your personal skills folder, ~/.claude/skills/. To scope it to one project, unzip it into the .claude/skills/ folder inside that project instead. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

After installing, check that the folder contains SKILL.md at its top level, along with the assets/ and references/ folders the skill uses.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ in your project folder
• Claude apps: Settings → Capabilities → Skills (upload the ZIP)

Trigger the skill with natural requests

You do not need to name the skill. The agent loads it when your request matches its description, which covers configuring HPA, configuring VPA, and applying best practices for GKE workload autoscaling. Describe your goal in plain words and mention the workload and namespace if you have them.

The skill's description also says when not to use it: cluster-level autoscaling (Cluster Autoscaler), static cluster sizing, and configuring node machine types directly. Ask those questions separately.

• Set up autoscaling for my checkout deployment in the shop namespace so it scales between 2 and 10 replicas on CPU.
• Show me how to turn on VPA in Off mode for my api deployment and read its recommendations.
• Review the resource requests in my GKE deployments and tell me where I am overprovisioned.

Example workflows the skill covers

The skill gives a quick command for HPA: kubectl autoscale with a CPU target and minimum and maximum replica counts. For version-controlled setups it points to a manifest template at assets/hpa-example.yaml, which the agent applies with kubectl apply and checks with kubectl get hpa.

For rightsizing, the skill describes a sequence: run VPA in Off mode for 24 hours or more, read the recommendations with kubectl describe vpa, compare target values against current requests, and apply new requests with a 20% buffer. A table in the skill maps conditions to recommendations, for example reducing a CPU request that is more than five times the P95 actual usage to P95 × 1.2.

What the skill needs and safety notes

You need kubectl access to a GKE cluster. The gcloud CLI is needed for enabling VPA on Standard clusters and for the attribution prefix the skill adds to gcloud commands. HPA requires Metrics Server, which is enabled by default on GKE. VPA is enabled by default on Autopilot but must be enabled manually on Standard clusters.

The skill does not run scripts and does not use the network, according to its listing. It does tell the agent to tag gcloud commands run in the terminal with a usage attribution variable that identifies only the skill and its version. Commands in generated scripts, Terraform, or user code are not tagged.

Be careful with VPA in Auto mode. The skill says it restarts pods to change resources, so a single-replica production service can have downtime. VPA by default requires at least two replicas before it evicts pods. Make sure your application handles SIGTERM. Use Pod Disruption Budgets during scaling and node upgrades.

• Requires: kubectl access to a GKE cluster, gcloud CLI, Metrics Server
• Runs scripts: no
• Uses network: no

Tips for good results

Define resource requests and limits in your containers first. The skill states that HPA and VPA rely on accurate requests. Start VPA in Off mode so you can review recommendations before anything restarts. Read each command the agent proposes before running it against a live cluster.

For application metrics such as Pub/Sub queue length, the skill recommends the External metric type. For Prometheus metrics, it mentions Google Cloud Managed Service for Prometheus or the Prometheus Adapter.

• Start with VPA in Off mode and review recommendations first.
• Never point HPA and VPA at the same metric.
• Confirm your app handles graceful shutdown before enabling Auto mode.