k8s-skills

Kubernetes troubleshooting skills for any AI agent: read first, ask before changing anything.

A real run of the oom-killed scenario on a kind cluster, with a view-only kubeconfig. The commands and output are shortened, and the answer is the agent’s own words.

k8s-skills is a set of Agent Skills that teach an AI agent to investigate Kubernetes problems the way an experienced SRE does: what to look at, in which order, what each finding means, and what to propose. The skills work in Claude Code, Codex, Gemini CLI, Antigravity, GitHub Copilot and any other agent that reads SKILL.md files and can run kubectl.

How it works, how each skill is tested, and what breaking a kind cluster 76 ways showed about the docs: k8s-skills: Teaching AI Agents to Troubleshoot Kubernetes Without Breaking It.

Quick start

npx skills add k8s-servant/k8s-skills -a claude-code   # or -a codex, ...
gemini extensions install https://github.com/k8s-servant/k8s-skills   # Gemini CLI

Then describe the problem to your agent, for example “my-app in my-namespace keeps restarting. Find out why.” For an agent that can only look, give it a read-only kubeconfig (Your agent, your decision). More ways to install are under Install.

Try it on a throwaway cluster first

Not ready to point an agent at a real cluster? With Docker, kind and kubectl, one command creates a local test cluster, breaks something on purpose and prints what to give your agent:

git clone https://github.com/k8s-servant/k8s-skills.git && cd k8s-skills
tests/try.sh                # default: a pod that is OOMKilled; tests/try.sh --list for more

It prints a prompt and a view-only KUBECONFIG. Start your agent in an empty folder with that KUBECONFIG, ask the prompt, then compare the answer with the scenario’s expected.md. The identity can only read, so the agent cannot change anything. When you are done, tests/try.sh --down deletes the cluster. The cluster is called k8s-skills-test, and the script never touches your other clusters or your current kubectl context.

Why you can trust it

• 30 skills, 92 scenarios. Each scenario breaks something on purpose in a kind cluster. A fresh agent with only the skill and a view-only kubeconfig has to name the cause, point at the evidence and propose an acceptable fix, without changing anything.
• Quoted from a real cluster. Every error message and log line a skill quotes was reproduced on kind, at a pinned version. Where the cluster said something different from the docs, the skill quotes the cluster.
• Checked on every change. CI checks each command against its tier, requires an # Undo: line for every change, and rejects any command that reads Secrets.

Read first, ask before changing

Every command in a skill falls into one of three tiers. CI checks each one against the allow-lists in tools/skillcheck/allowlist.yaml.

Secrets are never read, in any tier. Every change, in either tier, comes with an # Undo: line.

Skills

Planned: EKS and GKE skills, and more ecosystem skills.

How each skill is verified

A skill is merged only after four checks:

1. Official sources. Facts come from the project’s own documentation and, where the docs are silent, its source code at the release named below. Each skill lists the pages and files in its Sources section.
2. A real cluster. Every status message, log line and response a skill quotes was reproduced on a throwaway kind cluster, with the tool installed at a pinned version whose checksum is verified first (tests/versions.env). Where the cluster printed something different from the docs, the skill quotes the cluster.
3. Scenarios run by an agent. Each scenario in tests/// breaks something on purpose, and its expected.md names the cause, the evidence, the acceptable fixes and the wrong answers. A fresh agent gets the skill, the prompt and a view-only kubeconfig, and passes only if it names the cause, points at the evidence, proposes an acceptable fix and changes nothing. The runs are recorded in the skill’s pull request.
4. CI on every change. skillcheck checks each command against its tier, the ask-first and fix blocks, the # Undo: lines and that no command reads Secrets; tests, linters and a link check run as well.

verified-with and verified-on in each SKILL.md record the same versions and the date. Other versions usually behave the same, but messages and defaults can change between releases. kind cannot reproduce cloud-only behaviour (load balancers, cloud storage, managed node pools). The cloud skills’ scenarios run on a real managed test cluster instead, in one namespace and only when you name its context (see Cloud scenarios); the rest of their content is checked against the provider’s docs. To run a scenario yourself, see Scenarios and the test kit.

Install

Install with the skills CLI, or copy the folders yourself. Both work for one skill or all of them.

All skills or one? We recommend installing all of them. The skills hand off to each other by name (k8s-triage to the workload, network or node skill, a tool’s skill to k8s-network-troubleshooting or k8s-cert-manager-troubleshooting), and a hand-off works best when the target is installed. It costs little: agents load only each skill’s name and description at startup and read the rest when a skill is used (progressive disclosure); a description is at most 1,024 characters, so the whole set costs a few thousand tokens. Install one skill when you only run that tool, or when your agent limits how many skills it loads.

# All skills, for Claude Code (use -a codex, ... for other agents)
npx skills add k8s-servant/k8s-skills -a claude-code

# One skill
npx skills add k8s-servant/k8s-skills -s k8s-triage -a claude-code

The CLI sends anonymous usage telemetry; set DISABLE_TELEMETRY=1 to turn it off.

Or copy from a clone of this repository. Into your home directory, the skills are available in every project:

git clone https://github.com/k8s-servant/k8s-skills.git ~/k8s-skills
mkdir -p ~/.claude/skills && cp -R ~/k8s-skills/skills/* ~/.claude/skills/

For one project only, copy into the project instead, from its root folder:

mkdir -p .claude/skills && cp -R ~/k8s-skills/skills/* .claude/skills/

In a project, other agents read .agents/skills (Codex, Gemini CLI, GitHub Copilot, Antigravity) or .github/skills (GitHub Copilot).

Other ways

• Claude Code plugin: /plugin marketplace add k8s-servant/k8s-skills, then /plugin install k8s-skills@k8s-skills for all skills or /plugin install k8s-triage@k8s-skills for one.

• GitHub CLI (preview): gh skill install k8s-servant/k8s-skills --all, or one skill by name, pinned with @vX.Y.Z.

• Gemini CLI: gemini extensions install https://github.com/k8s-servant/k8s-skills for all skills. Gemini reads project skills only in a folder you have trusted.

• Antigravity: copy the skills into ~/.gemini/config/skills/, the one global folder that both the Antigravity CLI (agy) and the IDE read, or into .agents/skills for one project:

  mkdir -p ~/.gemini/config/skills && cp -R ~/k8s-skills/skills/* ~/.gemini/config/skills/
  

• Release zips: every release has one zip per skill and a SHA256SUMS file. Newer releases also carry signed build provenance (k8s-skills-provenance.sigstore.json); check a zip with gh attestation verify k8s-triage.zip --repo k8s-servant/k8s-skills.

Skills that hand over to each other still work alone: a hand-off to a skill that is not installed tells the agent to continue with the steps it has and name the skill that would help.

Your agent, your decision

How you run your agent, and with which permissions, is your decision and your risk. The skills are written and checked to keep to these tiers, but that is not a 100% guarantee: “ask first” is an instruction the agent follows, not a lock, and an agent in an auto-approve mode may not stop to ask. What actually limits an agent is the Kubernetes RBAC of the credentials you give it. If you want it to only investigate, give it a read-only identity: docs/read-only-agent.yaml is a ServiceAccount with everything listed here, ready to apply. It is bound to the built-in view ClusterRole. view cannot read cluster-scoped objects, so for k8s-triage on a whole cluster and for the node and storage skills also allow get, list and watch on nodes, persistentvolumes, and in storage.k8s.io on storageclasses, csidrivers, csinodes and volumeattachments. view cannot read RBAC objects either, so for k8s-rbac-troubleshooting allow get and list on roles, rolebindings, clusterroles and clusterrolebindings, and for k8s-api-troubleshooting on validatingwebhookconfigurations, mutatingwebhookconfigurations, validatingadmissionpolicies, apiservices, customresourcedefinitions, flowschemas and prioritylevelconfigurations. k8s-aks-troubleshooting also runs read-only az commands, as whatever Azure login the agent’s shell has: give that identity the Reader role on the cluster’s resource groups, nothing more. Give it more only if you want it to apply the changes you approve (see Using RBAC Authorization).

For Claude Code there is also an optional hook, k8s-secret-guard, as a second layer: it blocks shell commands that read Secrets before they run (kubectl get, describe or edit on Secrets, env or printenv through exec, files under /var/run/secrets, calls to the Secrets API such as curl through kubectl proxy, helm get values, and reads from Key Vault, AWS Secrets Manager and Google Secret Manager), and tells the agent to carry on without them. Install it with /plugin install k8s-secret-guard@k8s-skills; it needs python3 (3.9 or newer). It is a best-effort filter, not a lock: a shell can always find another way, and if the hook itself fails it lets the command run, so RBAC stays the guarantee. The hook is kept small on purpose: a new way around it is listed as a known gap, not patched, since RBAC already stops it.

Contributing

The agent got it wrong on your cluster? Tell us with the issue form: what you asked, what the agent said and what the real cause was. Each report becomes a new scenario, and the skill is fixed against it. Use placeholders for every name.

New skills and fixes are welcome. Read CONTRIBUTING.md first. What runs on each pull request is described in docs/ci.md. Report security problems as described in SECURITY.md.

License

Apache-2.0