Kubernetes Skill Pack

What This Pack Covers

Two skills: one that diagnoses why a pod is failing, branching on the specific failure signature; one that reviews a manifest before it’s applied. Kubernetes is a good domain for practicing a specific discipline from Security and Governance: both skills here are deliberately scoped to read-only diagnosis and review, explicitly excluding the destructive commands (kubectl delete, kubectl apply) that live right next to the safe, read-only ones in the same CLI.

Skill 1: k8s-pod-diagnose

---
name: k8s-pod-diagnose
description: Diagnoses why a Kubernetes pod is failing or not starting — CrashLoopBackOff, ImagePullBackOff, Pending, and OOMKilled states. Use when a pod is failing, stuck, or the user asks why a deployment isn't working.
metadata:
  version: "1.0.0"
compatibility: Requires kubectl configured with read access to the target cluster
---

## Available commands (read-only)

- `kubectl get pod <name> -o wide` — status and node placement
- `kubectl describe pod <name>` — events and container state detail
- `kubectl logs <name> --previous` — logs from the last crashed instance

## Diagnosis by status

- **CrashLoopBackOff** — check `logs --previous` first; this is almost
  always an application-level failure (unhandled exception, missing
  config, failed startup check), not a Kubernetes problem. Report the
  actual error from the logs, not just the pod status.
- **ImagePullBackOff** — check `describe pod` events for the specific pull
  error. Common causes: wrong image tag, private registry without
  imagePullSecrets configured, or a typo in the image name.
- **Pending** — check `describe pod` events for scheduling failures:
  insufficient CPU/memory on any node, an unsatisfied node selector or
  affinity rule, or an unbound PersistentVolumeClaim.
- **OOMKilled** — visible in `describe pod` under "Last State". This means
  the container exceeded its memory limit; report the configured limit
  and suggest reviewing whether it's set appropriately for the workload.

## Constraints

This skill is read-only. It diagnoses and reports — it does not restart,
delete, or scale anything. If a fix requires a cluster change, describe
what change is needed and let the user apply it themselves.

Pattern: Decision — the correct diagnosis path branches entirely on which failure signature is present, per Skill Design Patterns.

Skill 2: k8s-manifest-review

---
name: k8s-manifest-review
description: Reviews a Kubernetes manifest (Deployment, StatefulSet, or Pod spec) before it's applied — missing resource limits, missing probes, and risky security settings. Use when reviewing a manifest, before running kubectl apply, or when the user asks if a manifest is production-ready.
metadata:
  version: "1.0.0"
---

## Review checklist

1. **Resource requests and limits.** Flag any container missing `resources.
   requests` or `resources.limits` for CPU and memory — an unbounded
   container can starve or be starved by its neighbors on a shared node.
2. **Liveness and readiness probes.** Flag a missing `readinessProbe` on
   any container serving traffic — without it, Kubernetes may route
   traffic to a pod before it's actually ready. A missing `livenessProbe`
   is worth flagging too, though less severe.
3. **Privileged or root containers.** Flag `securityContext.privileged: true`
   or a missing `runAsNonRoot: true` as a security concern requiring
   explicit justification, not a default.
4. **`latest` image tags.** Flag any `image:` using the `latest` tag rather
   than a pinned version — this makes rollouts non-reproducible and
   rollback unreliable.

Report every finding, categorized as blocking (missing resource limits on
a production-bound manifest, privileged containers without justification)
or advisory (missing liveness probe, latest tag in a non-production
manifest).

Pattern: Validator, with the same blocking-vs-advisory severity distinction used in the SQL pack — not every finding deserves equal weight.

Why This Pack Stays Read-Only on Purpose

kubectl delete pod, kubectl apply -f, and kubectl scale are one command away from everything covered above, and it would be easy to fold “just apply the fix” into either skill. Deliberately not doing that is the point: a diagnosis skill that also takes destructive action collapses the review step a human would otherwise get before a cluster changes state. If you extend this pack for your own use, treat any skill that does apply changes as a separate, more tightly governed skill — with its own explicit confirmation requirements, following Security and Governance’s guidance on pairing destructive tools with stated constraints — rather than quietly adding that capability to a skill that was scoped as read-only.

Testing Both Skills

For k8s-pod-diagnose, you’ll get the most realistic signal by testing against real (or realistically reproduced) failure states rather than descriptions of them — a genuinely misconfigured image tag, an intentionally-too-low memory limit — since the diagnosis depends on correctly reading actual describe and logs output, not just recognizing a status name. For k8s-manifest-review, test against a manifest with every issue present, one that’s fully compliant, and one with only advisory-level issues — confirm advisory findings don’t get reported with the same urgency as blocking ones.

Summary

• k8s-pod-diagnose is a Decision skill branching on failure signature (CrashLoopBackOff, ImagePullBackOff, Pending, OOMKilled), strictly read-only
• k8s-manifest-review is a Validator checking resource limits, probes, security context, and image tags, with blocking-vs-advisory severity
• Both skills deliberately exclude destructive commands available right next to the read-only ones — a governance boundary worth keeping explicit rather than convenient
• Test diagnosis against real failure output, not just descriptions of failure types, since the skill’s value is in reading actual describe/logs output correctly

Next, the same read-only-first discipline applied to Terraform — plan review and drift detection before anything gets applied.