| name | kubernetes |
| description | Operate, troubleshoot, secure, upgrade, and automate Kubernetes clusters and workloads safely across upstream Kubernetes, k3s, RKE2, MicroK8s, k0s, Talos, OpenShift/OKD, kind, Minikube, Rancher-managed clusters, EKS, AKS, and GKE. Use when a task involves kubectl, Kubernetes APIs, Pods, Deployments, StatefulSets, Services, Ingress or Gateway API, CRDs, RBAC, NetworkPolicy, storage, scheduling, autoscaling, cluster lifecycle, or the bundled agent-first k8s-cli. |
Kubernetes
Use this skill as a decision and routing layer. Do not treat it as a static kubectl cheat sheet.
Operating contract
- Identify the target: distribution, provider, cluster version, client version, context, namespace, access mode, and whether the cluster is production.
- Discover before assuming: query served API resources, API versions, CRDs, system workloads, nodes, and distribution markers.
- Separate portable Kubernetes behavior from distribution/provider overlays. Load the matching reference before using lifecycle, networking, identity, storage, or upgrade instructions.
- For mutations, preview first (
k8s-cli ... --dry-run or kubectl diff / server dry-run), state scope, require explicit confirmation for destructive actions, then verify conditions, events, rollout, and the external boundary.
- Prefer stable APIs and server-side validation. Treat beta/alpha APIs, feature gates, provider defaults, and version numbers as time-sensitive.
- Keep evidence bounded and structured. Never dump kubeconfigs, Secret values, tokens, or unbounded logs into chat.
Choose the operating path
| Situation | First move | Do not do |
|---|
| Live cluster operation | Run doctor, context, and discover; record context, namespace, distribution, and versions | Do not infer cluster state from configuration or a prior command |
| No cluster access | Produce a bounded plan and name the missing prerequisite | Do not claim a diagnosis, success, or invented command output |
| Any mutation | Render, diff/server-dry-run, state scope, obtain the required confirmation, then mutate and verify the relevant boundary | Do not treat command exit 0 as operational success |
| Provider or distribution present | Load the matching overlay before applying portable guidance | Do not apply upstream instructions unchanged |
First-response discovery
scripts/k8s-cli --json doctor
scripts/k8s-cli --json context
scripts/k8s-cli --json discover
If the wrapper is unavailable, use the equivalent native commands from references/cli-reference.md. If kubectl is absent, stop and report the prerequisite rather than inventing cluster state.
Routing
| Scenario | Load |
|---|
| API discovery, SSA, CRDs, or deprecations | references/api-and-versioning.md |
| Workloads, probes, rollouts, jobs, or controllers | references/workloads-and-rollouts.md |
| Scheduling, scaling, storage, node disruption, or reliability | references/scheduling-scaling-storage.md and references/nodes-and-reliability.md |
| Services, DNS, NetworkPolicy, Ingress, or Gateway API | references/networking.md |
Pod is Running but not serving traffic or is absent from Service endpoints | references/workloads-and-rollouts.md, references/networking.md, references/troubleshooting.md, and the matching distribution overlay |
| RBAC, Pod Security, admission, audit, secrets, or policy engines | references/security-and-policy.md and references/policy.md |
| Evidence-first diagnosis or advanced debugging | references/troubleshooting.md and references/debugging.md |
| Backups, upgrades, HA, or observability | references/operations.md, references/backup-restore.md, and references/observability.md |
| Distribution/provider overlays or version matrix | references/distributions.md, references/version-skew.md, and references/source-index.md |
| Native command details or output contracts | references/cli-reference.md |
| Mutation safety gates | references/safety-gates.md |
Templates and scripts
templates/diagnostic-report.md: human-readable incident reporttemplates/cluster-inventory.json: bounded inventory schematemplates/upgrade-runbook.md: preflight, change, and verification runbookscripts/k8s-cli: agent-first wrapper around kubectlscripts/test-k8s-cli.sh: deterministic tests using a fake kubectlscripts/gather-cluster-state.sh: bounded diagnostic collection for incident reportsscripts/verify-cluster-health.sh: bounded post-operation health verificationscripts/refresh-version-matrix.sh: refreshes dated release observations, never silently edits guidance
Version policy
The research baseline was checked 2026-07-11. The Kubernetes project page reported maintained minors 1.36, 1.35, and 1.34. This is not a permanent claim. Refresh references/distributions.md and the source index before asserting current versions or support status.
Verification boundary
| Claim | Minimum evidence |
|---|
| Pod is healthy | Pod conditions, readiness, events, and relevant EndpointSlice or external boundary |
| Pod is serving traffic | Ready condition, Service selector, EndpointSlice membership, events, and a bounded Service-level check |
| Rollout succeeded | Controller conditions, resulting Pods, events, and the relevant Service or external check |
| API/resource is available | Served API discovery, installed CRDs/controller support, and server-side validation |
| Command succeeded operationally | Bounded command result plus the resource condition and user-visible boundary |
A component-level command result is evidence about that component only; do not promote it to a cluster or integration claim.
Hard boundaries
- Never expose Secret data or raw kubeconfig credentials.
- Never use
--force-conflicts, delete, drain, patch, upgrade, or cluster-reset procedures without explaining scope and obtaining the required confirmation.
- Never call a Pod
healthy from Running alone.
- Never call an integration successful from a component-level test alone.
- Never apply an upstream procedure to k3s, RKE2, a managed provider, Talos, or OpenShift without loading its overlay.
