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 KiB

Raw Permalink Blame History

title	description
/operator-audit — Slash Command for AI Coding Agents	Run the full Kubernetes Operator audit (CRD + reconcile + capability) on the current repo. Slash command for Claude Code, Codex CLI, Gemini CLI.

/operator-audit

:material-console: Slash Command :material-github: Source

Run the full audit on a Kubernetes Operator repository:

Validate every CRD YAML against operator-pattern best practices
Lint every Go controller's reconcile function for anti-patterns
Score the operator against OperatorHub Capability Levels (1-5)
Output a markdown report with pass/fail per check and concrete next steps

Usage

/operator-audit
/operator-audit --operator-dir ./my-operator
/operator-audit --crd-dir ./config/crd --controller-dir ./controllers

Implementation

SKILL=engineering/kubernetes-operator/skills/kubernetes-operator
DIR="${OPERATOR_DIR:-.}"

echo "## CRD validation"
python "$SKILL/scripts/crd_validator.py" --crd "$DIR/config/crd" || true

echo ""
echo "## Reconcile lint"
python "$SKILL/scripts/reconcile_lint.py" --controller "$DIR/controllers" || python "$SKILL/scripts/reconcile_lint.py" --controller "$DIR/internal/controller" || true

echo ""
echo "## Capability audit"
python "$SKILL/scripts/operator_capability_audit.py" --operator-dir "$DIR"

Output

A markdown report with:

CRD findings per file: FAIL / WARN / PASS for each check
Reconcile findings: line-numbered anti-patterns
Current capability level + concrete advancement steps

Pre-conditions

Run from a Kubernetes Operator repository
Go controllers expected at controllers/ or internal/controller/
CRDs expected at config/crd/ (kubebuilder layout)
kubernetes-operator skill installed

Post-conditions

Markdown report streamed to terminal
Exit code 0 if all PASS; 1 if any FAIL

2 KiB Raw Permalink Blame History