kubernetes-operator

name	kubernetes-operator
description	Use when building a Kubernetes Operator — custom controllers that reconcile CRD state. Triggers on "build an operator", "CRD design", "reconcile loop", "controller-runtime", "kubebuilder", "operator-sdk", "metacontroller", "KOPF", "operator capability levels", or "custom resource". Ships CRD validator, reconcile-loop linter, and OperatorHub capability auditor (all stdlib Python), 4 references on the operator pattern + CRD design + reconcile patterns + tooling landscape, and a /operator-audit slash command. NOT a generic k8s skill — specifically the Operator pattern.
context	fork
version	2.9.0
author	claude-code-skills
license	MIT
tags	["kubernetes","operator","crd","controller-runtime","kubebuilder","operator-sdk","metacontroller","kopf","reconcile","devops"]
compatible_tools	["claude-code","codex-cli","cursor","antigravity","opencode","gemini-cli"]

Kubernetes Operator

Build operators that reconcile correctly. Most operator bugs are not Kubernetes bugs — they are reconcile-loop bugs: missing finalizers, blocking calls, no requeue on transient errors, status drift, RBAC over-grants. This skill catches them deterministically before they reach a cluster.

When to use

• Building a new Kubernetes Operator (controller for a CRD)
• Reviewing an existing operator for capability-level gaps
• Auditing a CRD spec for status/conditions/finalizer correctness
• Choosing a framework (controller-runtime / kubebuilder / operator-sdk / metacontroller / KOPF)
• Designing the API surface of a Custom Resource
• Hardening RBAC, leader election, or webhook validation

When NOT to use

• Plain Helm chart packaging → use helm-chart-builder
• Standard kubectl operations / blue-green deploys → use senior-devops
• General k8s security posture → use cloud-security
• "I want to run a workload" — that's a Deployment / Job, not an operator

Core principle: an operator is a reconcile loop, not a script

observe(actual) → desired = read(spec) → diff(actual, desired) → act → update(status)
                                                                          ↓
                                                                   requeue / done

Operators that fail are the ones that:

1. Treat reconcile as imperative (do this, then this, then this) instead of declarative (make actual=desired, idempotently)
2. Don't requeue transient failures
3. Don't use finalizers, leaving orphan resources
4. Mutate spec instead of status
5. Don't use the status subresource (status updates trigger spec reconciles → loop)
6. Block in reconcile (long HTTP calls, locks)
7. Forget leader election → split-brain on multi-replica deploys

The 3 tools below catch each of these.

Quick start

SKILL=engineering/kubernetes-operator/skills/kubernetes-operator

# Validate a CRD design
python "$SKILL/scripts/crd_validator.py" --crd config/crd/myapp.yaml

# Lint a Go reconcile function
python "$SKILL/scripts/reconcile_lint.py" --controller controllers/myapp_controller.go

# Score against OperatorHub Capability Levels (1-5)
python  --operator-dir .