k8s-skills

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

imageCI imageRelease imageLicense

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, 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.

Why you can trust it

• 26 skills, 79 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/<skill>/<case>/ 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) 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.

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, for example one 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).

Contributing

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