Kubernetes Health

Run read-only Kubernetes health checks and report cluster status with evidence. This skill works without private overlays by requiring an explicit kube context or confirmed current context. Local users may add ignored protected overlays for aliases and environment-specific checks.

When to use

• User asks to check cluster health, status, diagnostics, node status, or post-maintenance state
• Verifying cluster-wide symptoms after upgrades, reboots, Helm changes, GitOps syncs, or incidents
• Gathering read-only evidence across nodes, workloads, events, ingress, storage, logs, and policy
• Producing a short traffic-light report from Kubernetes and related observability signals

When NOT to use

• Writing or reviewing Kubernetes manifests - use kubernetes
• Writing Helm charts, Kustomize overlays, or IaC - use kubernetes or terraform
• Changing resources, restarting pods, deleting objects, or applying fixes - ask for explicit escalation
• Debugging one application deeply after the broad sweep identifies it - use the relevant domain skill
• Unknown-root-cause debugging or triage - use debug-triage

---

AI Self-Check

Before running checks or reporting results, verify:

• Target context is explicit or the current context was confirmed
• Every kubectl command includes --context <context>
• Every helm command includes --kube-context <context>
• Commands are read-only: no apply, patch, delete, edit, rollout restart, scale, cordon, drain, or exec unless the user explicitly escalates
• Output is capped with head, tail, --since, --field-selector, or selectors
• Time window is bounded and stated in the report
• Protected registry contents are not printed unless the user asks for those exact details
• Findings include evidence, impact, and next action
• No improvisation: reference checks or verified read-only follow-ups used confirmed object names and supported flags; missing coverage was reported
• Stderr is visible: diagnostic commands surface their failure reason instead of masking it with 2>/dev/null; a missing tool, permission gap, or wrong context is reported, not silently treated as a clean result
• Cross-cutting agent hygiene applied - see references/agent-hygiene.md

Performance

• Start with cluster-wide signals before loading symptom-specific references.
• Prefer summarized evidence over dumping raw Kubernetes output into context.

Best Practices

• Separate health evidence from remediation; fixes require a separate escalation.
• Start with the reference checks. Use verified read-only follow-ups against discovered objects when needed to establish health; never guess service names, namespaces, paths, or flags.
• Do not read a metric's status without knowing what the metric measures. The reference files state what each signal does and does NOT represent; misreading a percentage or a stale value produces a confidently wrong report.

Cluster Registry

This public skill has no built-in private cluster registry.

Users may create local-only overlays under skills/kubernetes-health/protected/ for private lab, homelab, work, or customer cluster details. The directory is gitignored by this collection. If it exists in the installed skill, read it while using this skill. A user can ask their agent to create or update these files.

Suggested local layout:

protected/
  registry.md            # aliases, kube contexts, CWD patterns, profile mappings
  private-patterns.txt   # terms that must never appear in public files
  <cluster-or-env>.md    # local namespaces, runbooks, dashboards, thresholds

1. If protected/registry.md exists, read it first and use its alias, context, CWD pattern, and reference mappings.
2. If the registry maps the target to protected/<cluster-or-env>.md, read that profile before running checks.
3. If no protected registry exists, require an explicit kube context or ask before using the current context.
4. Never guess a cluster from a vague request.
5. Never print protected registry contents in public reports unless the user asks for those exact details.
6. Treat gitignored as local privacy, not encryption. Do not put protected overlays in shared logs, issues, PR comments, or public reports.

Usage

kubernetes-health [context-or-alias] [timewindow]

• context-or-alias is a kube context, current-context confirmation, or protected overlay alias.
• timewindow defaults to 2h; use bounded values such as 30m, 1h, 2h, 6h, or 24h.

Workflow

Copy this checklist and track progress:

• Step 1: Target context resolved (explicit or confirmed)
• Step 2: Context and time window stated; read-only scope confirmed
• Step 3: Sweep run (on a wrong-context or unreachable-cluster error, return to Step 1)
• Step 4: Findings classified GREEN/YELLOW/RED
• Step 5: Report returned with evidence and next actions

Step 1: Resolve target

If a protected registry maps the request or current directory to an alias, use that mapping. If no mapping exists, require an explicit kube context or ask whether to use kubectl config current-context.

Step 2: Confirm read-only scope

State the context and time window before running commands. Do not run mutation commands as part of this skill.

Step 3: Run the generic sweep

Treat generic health, cluster-wide, and post-maintenance requests as broad sweeps: run references/kubernetes-core.md, references/helm-gitops.md, references/networking-ingress.md, references/storage.md, and references/monitoring-logs.md. For a narrower symptom-scoped request, start with references/kubernetes-core.md and load only the matching references below. Load references/security.md when policy, RBAC, or image risk is in scope or the core sweep exposes it.

• networking or certificate symptoms -> references/networking-ingress.md
• release or reconciliation symptoms -> references/helm-gitops.md
• pending pods or volume symptoms -> references/storage.md
• noisy errors or alert symptoms -> references/monitoring-logs.md
• policy, RBAC, or image-risk symptoms -> references/security.md

Step 4: Classify findings

Use GREEN for healthy signals, YELLOW for degraded or ambiguous state, and RED for user-visible outage, data-risk, or control-plane risk. Distinguish transient rollout noise from persistent degradation.

Step 5: Report

Return a concise report:

# Cluster Health Report - <context> (<timewindow>, YYYY-MM-DD HH:MM)

## Summary
- STATUS: GREEN|YELLOW|RED
- Scope: <contexts, namespaces, time window>
- Key findings: <short bullets>

## Evidence
- <area>: <command or source> -> <observed signal>

## Next Actions
- <read-only follow-up or explicit escalation request>

Reference Files

• references/kubernetes-core.md - nodes, workloads, events, namespaces, and resource pressure
• references/helm-gitops.md - Helm releases, GitOps controllers, and reconciliation state
• references/networking-ingress.md - services, ingress, Gateway API, load balancers, DNS, and certificates
• references/storage.md - PVs, PVCs, CSI drivers, storage classes, and volume attachment
• references/monitoring-logs.md - alerts, metrics availability, log triage, and noisy namespaces
• references/security.md - read-only checks for RBAC, secrets exposure signals, image risk, and policy engines

Output Contract

See references/output-contract.md for the full contract.

• Skill name: KUBERNETES-HEALTH
• Deliverable bucket: audits
• Mode: conditional. When invoked to analyze, review, audit, or improve existing repo content, apply the reporting size and evidence rules in references/output-contract.md and write the deliverable to docs/local/audits/kubernetes-health/<YYYY-MM-DD>-<slug>.md. When invoked to answer a question, teach a concept, build a new artifact, or generate content, respond freely without the contract.
• Severity scale: P0 | P1 | P2 | P3 | info (see shared contract; only used in audit/review mode).

Related Skills

• kubernetes - write or review manifests, Helm charts, Kustomize, and GitOps config
• networking - debug DNS, routing, proxies, VPNs, and Linux networking
• security-audit - review security controls or vulnerability posture beyond read-only cluster signals
• terraform - change infrastructure definitions or state

Rules

1. Read only. Do not mutate cluster state unless the user explicitly changes the task.
2. Report failed checks as findings; do not hide missing tools, missing CRDs, or permission errors.
3. Use reference checks and verified read-only follow-ups against the confirmed target. Discover object names, verify flags, and report missing coverage. Mutation still requires explicit escalation.