kubernetes-health

| Impact | Value |

|--------|-------|

| Token Savings | ~70% vs manual kubectl exploration |

| Setup Time | 0 min (uses existing kubectl config) |

| Coverage | Adapts to installed operators automatically |

Known Issues Prevented

| Problem | Root Cause | How This Skill Helps |

|---------|------------|---------------------|

| Missing operator health | Static checklists miss CRDs | Dynamic API discovery detects all installed operators |

| Stale diagnostics | Manual checks become outdated | Real-time cluster API interrogation |

| Incomplete coverage | Unknown cluster configuration | Automatically activates relevant sub-agents |

1. Verify cluster access: Ensure kubectl is configured and can reach your cluster
2. Run discovery: Execute discover_apis.py to detect installed operators
3. Dispatch agents: Use the orchestrator to run health checks based on discovery

```bash

# Step 1: Verify kubectl context

kubectl config current-context

kubectl cluster-info

# Step 2: Run API discovery

uv run .claude/skills/kubernetes-health/scripts/discover_apis.py

# Step 3: Review detected operators and dispatch health agents

```

Always

• Verify kubectl context before running health checks
• Use read-only kubectl commands (get, describe, logs)
• Run core health checks before operator-specific checks
• Aggregate results using the provided scoring methodology

Never

• Modify cluster resources during health checks
• Expose secret values in health reports (metadata only)
• Skip context verification for production clusters
• Assume operator presence without API discovery

Common Mistakes

| Mistake | Why It's Wrong | Correct Approach |

|---------|----------------|------------------|

| Hardcoding operator checks | Misses installed operators, checks missing ones | Use API discovery to detect what's installed |

| Sequential agent dispatch | Slow for multi-operator clusters | Run operator agents in parallel (same priority) |

| Raw kubectl output | Token inefficient, hard to parse | Use scripts for condensed JSON output |

Scripts

| Script | Purpose |

|--------|---------|

| scripts/discover_apis.py | Discovers all API groups and detects installed operators |

| scripts/health_orchestrator.py | Maps discovered APIs to specialized health agents |

| scripts/aggregate_report.py | Aggregates multi-agent results into unified report |

References

| File | Contents |

|------|----------|

| references/operator-checks.md | Detailed health checks for each supported operator |

| references/health-scoring.md | Scoring methodology and weight assignments |

Templates

| File | Purpose |

|------|---------|

| templates/health-report.json | JSON schema for health report output |

Required

| Package | Version | Purpose |

|---------|---------|---------|

| kubectl | Latest | Cluster interaction |

| Python | >= 3.11 | Script execution |

| uv | Latest | Python script runner |

Optional

| Package | Version | Purpose |

|---------|---------|---------|

| kubernetes | >= 28.1.0 | Python client (for advanced discovery) |

The skill automatically detects and dispatches specialized agents for:

| Operator | API Group | Agent |

|----------|-----------|-------|

| Core K8s | (always) | k8s-core-health-agent |

| Crossplane | crossplane.io | k8s-crossplane-health-agent |

| ArgoCD | argoproj.io | k8s-argocd-health-agent |

| Cert-Manager | cert-manager.io | k8s-certmanager-health-agent |

| Prometheus | monitoring.coreos.com | k8s-prometheus-health-agent |

| Status | Score Range | Criteria |

|--------|-------------|----------|

| HEALTHY | 90-100 | All checks pass, no warnings |

| DEGRADED | 60-89 | Some warnings, no critical issues |

| CRITICAL | 0-59 | Critical issues affecting availability |

kubectl connection issues

```bash

# Verify context

kubectl config current-context

# Test connectivity

kubectl cluster-info

# Check permissions

kubectl auth can-i get pods --all-namespaces

```

Discovery returns empty results

• Ensure cluster is reachable
• Check RBAC permissions for API discovery
• Verify kubectl version compatibility

Agent dispatch failures

• Confirm discovered API group matches agent trigger
• Check agent file exists in .claude/agents/specialized/kubernetes/
• Review agent tool restrictions

• [ ] kubectl configured and connected to cluster
• [ ] Python 3.11+ installed
• [ ] uv installed for script execution
• [ ] Read permissions on cluster resources
• [ ] Agent files present in .claude/agents/specialized/kubernetes/