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

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