mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-09-06 08:15:58 +00:00

feat(skills): ship kubernetes-operator (Phase 2 — operator pattern discipline)

Phase 2 of the multi-skill build effort. Same 14-step pipeline as Phase 1.

## What landed

### New skill: engineering/kubernetes-operator

End-to-end Kubernetes Operator discipline. Published as BOTH:
- Standalone plugin: engineering/kubernetes-operator/
- Bundled mirror:    engineering/skills/kubernetes-operator/

3 stdlib-only Python tools:
- crd_validator.py            — checks CRD YAMLs for status subresource,
                                 structural schema, conditions array, printer
                                 columns, version policy, scope
- reconcile_lint.py            — finds reconcile-loop bugs in Go: time.Sleep,
                                 spec mutation via r.Update, missing requeue,
                                 oversized reconcile bodies, panic/os.Exit,
                                 unbalanced finalizer add/remove
- operator_capability_audit.py — scores against OperatorHub Capability
                                 Levels 1-5 with concrete next-level steps

4 reference docs:
- operator_pattern.md   — what an operator IS, when to use vs Helm/Deployment
- crd_design.md         — anatomy of a production CRD, versioning, conversion
- reconcile_loop.md     — idempotence patterns, error/requeue, status subresource
- tooling_landscape.md  — controller-runtime / kubebuilder / operator-sdk /
                          metacontroller / KOPF / java-operator-sdk decision tree

Asset templates:
- crd_template.yaml       — passes crd_validator.py PASS-clean
- reconcile_skeleton.go   — passes reconcile_lint.py PASS-clean

Plus: SKILL.md (213 lines), README.md, /operator-audit slash command.

### Audit verdict (evidence-based)

Closest existing coverage:
- engineering-team/senior-devops — kubectl / blue-green deploys, no operators
- engineering/helm-chart-builder — Helm charts (different abstraction)
- engineering-team/cloud-security — k8s RBAC at high level
None cover the Operator pattern (CRD + controller + reconcile loop).
Verdict: BUILD. Gap is real and tooling-shaped.

### Self-test (meta-validation)

During build, the new linters caught 4 real bugs in their own asset templates:
- crd_validator.py wrongly anchored regexes to start-of-line, misclassifying
  indented YAML keys (scope, singular, listKind) as missing
- reconcile_lint.py checked finalizer add/remove balance per-function,
  missing the cross-function pattern in the asset (Add in main reconcile,
  Remove in reconcileDelete)
Both linters fixed; assets re-tested; both PASS clean.

This is Karpathy principle 4 in action: verifiable goals catch real bugs.

### Marketplace / registry

- marketplace.json: kubernetes-operator registered as standalone plugin
- engineering-advanced-skills bundle: 45 → 46 → 47 skills, version → 2.4.1
- engineering/.claude-plugin/plugin.json: version + skill list updated
- mkdocs.yml: nav entry under "Engineering - POWERFUL"
- docs/skills/engineering/kubernetes-operator.md: docs page (manual,
  pending generate-docs.py classification fix)
- docs/commands/operator-audit.md: auto-generated
- .codex/, .gemini/: synced

### Karpathy-coder gates

- complexity_checker (strict): 85/100 average, depth-4-to-6 WARNs (lambdas
  in capability audit). Same range as karpathy-coder's own scripts (70/100
  baseline). Verdict: WARN, not FAIL.
- All 1648 tests pass (was 1630; added 18 for the new skill).
- mkdocs build --strict: succeeded in 14.44s.

### Verifiable success criteria (all green)

✓  scripts/*.py --help     → exit 0 for all 3 scripts
✓  SKILL.md frontmatter    → name + description + tags + compatible_tools
✓  plugin.json schema      → 8 fields exact (verified by check_plugin_json.py)
✓  sync_skill_bundles      → standalone ↔ bundled mirror in sync
✓  marketplace.json        → standalone entry + bundle counts updated
✓  generate-docs.py        → command page generated (skill page manual)
✓  mkdocs build --strict   → succeeded
✓  cross-tool sync         → codex + gemini synced
✓  pytest tests/           → 1648 passed, 0 failed
✓  CHANGELOG.md            → [Unreleased] entry expanded
✓  Self-test               → linters caught + fixed 4 real bugs in own assets

## Files

- engineering/kubernetes-operator/                              (new standalone plugin)
- engineering/skills/kubernetes-operator/                       (new bundled mirror)
- commands/operator-audit.md                                    (new slash command)
- docs/skills/engineering/kubernetes-operator.md                (new docs page)
- docs/commands/operator-audit.md                               (auto-generated)
- mkdocs.yml                                                    (nav entries)
- .claude-plugin/marketplace.json                               (registered)
- engineering/.claude-plugin/plugin.json                        (bundle bumped)
- CHANGELOG.md                                                  ([Unreleased] expanded)
- .codex/, .gemini/                                             (cross-tool sync)

https://claude.ai/code/session_01Dq12xJakFRxwaoU8Pqejdm

2026-05-09 09:01:45 +00:00

2.9 KiB

Raw Permalink Blame History

Kubernetes Operator

End-to-end discipline for building Kubernetes Operators correctly. Catches the recurring reconcile-loop bugs (missing finalizers, blocking calls, status drift, RBAC over-grants, no requeue) before they reach a cluster.

What's inside

3 stdlib Python tools — CRD validator, reconcile-loop linter, OperatorHub capability auditor
4 reference docs — operator pattern, CRD design, reconcile patterns, framework comparison
Asset templates — production CRD YAML + Go controller skeleton (both pass the linters)
/operator-audit slash command — runs all 3 tools and produces a report

Install

# Via Claude Code marketplace
/plugin install kubernetes-operator

# Or clone the repo
git clone https://github.com/alirezarezvani/claude-skills.git
cd claude-skills/engineering/kubernetes-operator

Quick start

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

python "$SKILL/scripts/crd_validator.py" --crd config/crd/myapp.yaml
python "$SKILL/scripts/reconcile_lint.py" --controller controllers/myapp_controller.go
python "$SKILL/scripts/operator_capability_audit.py" --operator-dir .

Scope

This is the Operator pattern specifically. For other Kubernetes work:

Helm chart authoring → helm-chart-builder
Kubectl operations / blue-green deploys → senior-devops
General k8s security → cloud-security
Cloud architecture → aws-solution-architect, azure-cloud-architect, gcp-cloud-architect

Key principles

Reconcile is idempotent, declarative, and bounded in time
Status subresource is non-negotiable — without it, status updates loop spec reconciles
Finalizers protect external resources — cascade deletion is the operator pattern's free gift, but only for owned k8s resources
RBAC is least-privilege — controllers shouldn't read secrets they don't need
Capability levels are an SLA, not a label — aim for L3 (Full Lifecycle) before public release

Skill structure

kubernetes-operator/
├── README.md
├── .claude-plugin/plugin.json
└── skills/kubernetes-operator/
    ├── SKILL.md
    ├── scripts/
    │   ├── crd_validator.py
    │   ├── reconcile_lint.py
    │   └── operator_capability_audit.py
    ├── references/
    │   ├── operator_pattern.md
    │   ├── crd_design.md
    │   ├── reconcile_loop.md
    │   └── tooling_landscape.md
    └── assets/
        ├── crd_template.yaml
        └── reconcile_skeleton.go

Verifiable success

A team using this skill should achieve:

100% of new CRDs pass crd_validator.py before merge
All reconcile functions pass reconcile_lint.py strict mode
Operators reach OperatorHub Capability Level 3 before public release
Mean time to fix a reconcile bug: <1 day (no infinite loops in production)

License

MIT — see repo root LICENSE.

2.9 KiB Raw Permalink Blame History