# kubernetes-skill

Adopt this skill: https://proskills.md/skills/other/lukasniessen-kubernetes-skill

Page: https://proskills.md/skills/other/lukasniessen-kubernetes-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 4747
upstream: https://github.com/lukasniessen/kubernetes-skill/blob/HEAD/SKILL.md

```text
---
name: kubernetes-skill
description: "Prevent Kubernetes hallucinations by diagnosing and fixing failure modes: insecure workload defaults, resource starvation, network exposure, privilege sprawl, fragile rollouts, and API drift. Use when generating, reviewing, refactoring, or migrating manifests, Helm charts, Kustomize overlays, cluster policies, and platform-specific Kubernetes work for EKS, GKE, AKS, OpenShift, GitOps controllers, or observability stacks."
---

# KubeShark: Failure-Mode Workflow for Kubernetes

Run this workflow top to bottom.

## 1) Capture execution context

Record before writing manifests:
- cluster version (e.g. 1.30, 1.31) and distribution (EKS, GKE, AKS, k3s, vanilla)
- target namespace and environment criticality (dev/staging/prod)
- workload type (Deployment, StatefulSet, Job, CronJob, DaemonSet)
- deployment method (raw YAML, Helm, Kustomize, operator-managed)
- policy enforcement (Pod Security Admission level, Kyverno, OPA/Gatekeeper)
- cloud provider and CNI (affects networking, storage classes, load balancers)
- platform controllers/add-ons (GitOps, observability, ingress, service mesh, autoscaling)

If unknown, state assumptions explicitly.

## 2) Diagnose likely failure mode(s)

Select one or more based on user intent and risk:
- insecure workload defaults: missing security contexts, PSS violations, host access
- resource starvation: missing requests/limits, no PDB, scheduling chaos
- network exposure: flat networking, missing policies, wrong Service types, DNS issues
- privilege sprawl: overly permissive RBAC, leaked secrets, excess ServiceAccount rights
- fragile rollouts: misconfigured probes, mutable tags, unsafe update strategies
- API drift: wrong apiVersion, deprecated APIs, schema violations, tool-specific errors

## 3) Load only the relevant reference file(s)

Primary failure-mode references:
- `references/insecure-workload-defaults.md`
- `references/resource-starvation.md`
- `references/network-exposure.md`
- `references/privilege-sprawl.md`
- `references/fragile-rollouts.md`
- `references/api-drift.md`

Supplemental references (only when needed):
- `references/deployment-patterns.md`
- `references/stateful-patterns.md`
- `references/job-patterns.md`
- `references/daemonset-operator-patterns.md`
- `references/security-hardening.md`
- `references/observability.md`
- `references/multi-tenancy.md`
- `references/storage-and-state.md`
- `references/helm-patterns.md`
- `references/kustomize-patterns.md`
- `references/validation-and-policy.md`
- `references/examples-good.md`
- `references/examples-bad.md`
- `references/do-dont-patterns.md`

Conditional Reference Retrieval (CRR) references (load only when the signal is detected):
- `references/conditional/eks-patterns.md` for EKS, AWS, IRSA, EKS Pod Identity, AWS Load Balancer Controller, EBS/EFS CSI, Karpenter
- `references/conditional/gke-patterns.md` for GKE, Autopilot, Workload Identity Federation for GKE, Dataplane V2, GCE Ingress, Config Sync
- `references/conditional/aks-patterns.md` for AKS, Microsoft Entra Workload ID, Azure CNI, AGIC, Azure Disk/File/Blob CSI
- `references/conditional/openshift-patterns.md` for OpenShift, OKD, ROSA, ARO, Routes, SCCs, OLM, `oc`
- `references/conditional/gitops-controllers.md` for Argo CD, ApplicationSet, Flux, GitOps reconciliation, sync waves
- `references/conditional/observability-stacks.md` for Prometheus Operator, ServiceMonitor, PodMonitor, OpenTelemetry, Loki, Grafana

Do not load multiple CRR files unless the task spans multiple detected platforms/tools.

## 4) Propose fix path with explicit risk controls

For each fix, include:
- why this addresses the failure mode
- what could still go wrong at deploy time or runtime
- guardrails (validation commands, policy checks, rollback path)

## 5) Generate implementation artifacts

When applicable, output:
- Kubernetes manifests (YAML with security contexts, resource limits, labels)
- Helm values/templates or Kustomize overlays
- NetworkPolicies, RBAC resources, PodDisruptionBudgets
- Policy rules (Kyverno/OPA) and admission controls

## 6) Validate before finalize

Always provide validation steps tailored to deployment method and risk tier:
- `kubectl apply --dry-run=server` or `kubectl diff`
- `kubeconform` for schema validation against target cluster version
- cross-resource consistency check (label/selector/port alignment)
- policy scan (PSS profile check, Kyverno/OPA audit)
Never recommend direct production apply without reviewed diff and approval.

## 7) Output contract

Return:
- assumptions and cluster version floor
- selected failure mode(s)
- chosen remediation and tradeoffs
- validation/test plan
- rollback/recovery notes (rollout undo, revision history, data safety)
```

## File: README.md
upstream: https://github.com/lukasniessen/kubernetes-skill/blob/HEAD/README.md

````text
# Kubernetes Skill for Claude Code and Codex: KubeShark

<div align="center" name="top">
  <img align="center" src="assets/logo.png" width="180" height="180" alt="KubeShark Logo">

<!-- spacer -->
<p></p>

[![Claude Skill](https://img.shields.io/badge/Claude-Skill-6272F5)](https://docs.claude.ai/docs/agent-skills)
[![Codex Skill](https://img.shields.io/badge/Codex-Skill-10A37F)](https://developers.openai.com/codex/skills/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub stars](https://img.shields.io/github/stars/LukasNiessen/kubernetes-skill.svg)](https://github.com/LukasNiessen/kubernetes-skill)

</div>

The #1 Kubernetes skill for Claude Code and Codex, measured by GitHub stars.

### Fixes Hallucinations.

LLMs hallucinate a lot when it comes to Kubernetes. They omit security contexts, generate deprecated APIs, use wildcard RBAC, forget resource limits, and produce probes that cause cascading failures. This skill fixes it. It includes best practices for Kubernetes -- good, bad, and neutral examples so the AI avoids common mistakes. Using KubeShark, the AI keeps proven practices in mind, eliminates hallucinations, and defaults to secure, reliable, production-ready manifests.

KubeShark is built as the production-grade Kubernetes skill for Claude Code and Codex: broader than resource-template skills, safer than generic Kubernetes prompts, and tuned for hallucination prevention instead of raw tutorial volume.

### Very Token-Efficient.

Most Kubernetes skills dump huge walls of text onto the agent and burn expensive tokens -- with no upside. LLMs don't need the entire Kubernetes docs again. KubeShark was aggressively de-duplicated and optimized for maximum quality per token.

### Based on Official Best Practices.

KubeShark is primarily based on the [official Kubernetes documentation](https://kubernetes.io/docs/), the [NSA/CISA Kubernetes Hardening Guide](https://media.defense.gov/2022/Aug/29/2003066362/-1/-1/0/CTR_KUBERNETES_HARDENING_GUIDANCE_1.2_20220829.PDF), [OWASP Kubernetes Top 10](https://owasp.org/www-project-kubernetes-top-ten/), [Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/), and the [CIS Kubernetes Benchmark](https://www.cisecurity.org/benchmark/kubernetes). When guidance conflicts, it prioritizes official Kubernetes documentation.

---

[Quick Start](#-quick-start) · [Why KubeShark](#-why-kubeshark) · [Token Strategy](#-token-strategy) · [What's Included](#-whats-included) · [How It Works](#-how-it-works) · [Sponsor](https://github.com/sponsors/LukasNiessen) · [Philosophy](PHILOSOPHY.md)

---

## 2 min Quickstart

### Option 1: Skills CLI

If you manage skills with the `skills` CLI, install KubeShark directly from GitHub:

```bash
npx skills add https://github.com/lukasniessen/kubernetes-skill --skill kubernetes-skill
```

### Option 2: Clone

**macOS / Linux:**

```bash
git clone https://github.com/LukasNiessen/kubernetes-skill.git ~/.claude/skills/kubernetes-skill
```

**Windows (Powershell):**

```powershell
git clone https://github.com/LukasNiessen/kubernetes-skill.git "$env:USERPROFILE\.claude\skills\kubernetes-skill"
```

**Windows (Command Prompt):**

```powershell
git clone https://github.com/LukasNiessen/kubernetes-skill.git "%USERPROFILE%\.claude\skills\kubernetes-skill"
```

That's it. Claude Code auto-discovers skills in `~/.claude/skills/` -- no restart needed.

### Option 3: Marketplace

Claude Code has a built-in plugin system with marketplace support. Instead of cloning manually, you can add KubeShark's marketplace and install directly from the CLI:

```
/plugin marketplace add LukasNiessen/kubernetes-skill
/plugin install kubernetes-skill
```

Or use the interactive plugin manager -- run `/plugin`, switch to the **Discover** tab, and install from there. The marketplace reads the `.claude-plugin/marketplace.json` in this repo to register KubeShark as an installable plugin.

### Option 4: Codex

Codex has no global skill system -- setup is per-project. Clone KubeShark into your repo and reference it from your `AGENTS.md`:

```bash
# Clone into your project root
git clone https://github.com/LukasNiessen/kubernetes-skill.git .kubernetes-skill
```

Then add to your `AGENTS.md` (or create one in the repo root):

```markdown
## Kubernetes

When working with Kubernetes manifests, Helm charts, or Kustomize overlays, follow the workflow in `.kubernetes-skill/SKILL.md`.
Load references from `.kubernetes-skill/references/` as needed.
```

### That's it!

Done. Now ask Claude Code / Codex any Kubernetes question. KubeShark responses follow the 7-step failure-mode workflow and include an output contract with assumptions, tradeoffs, and rollback notes.

**Invoke explicitly:**

```bash
/kubernetes-skill Create a production-ready Deployment with an Ingress and autoscaling
```

```bash
/kubernetes-skill Review my Deployment for security issues and add proper RBAC, NetworkPolicies, and resource limits
```

**Or just ask naturally** -- KubeShark activates automatically for any Kubernetes task:

```
Review my deployment.yaml for security issues
```

```
Create a Helm chart for a PostgreSQL StatefulSet with backup CronJobs
```

## Why KubeShark

### Overview

| Dimension                       | **KubeShark**                                          | **No Skill** |
| ------------------------------- | ------------------------------------------------------ | ------------ |
| **SKILL.md activation cost**    | Low, procedural workflow only                          | 0            |
| **Reference granularity**       | 26 focused files                                       | --           |
| **Token burn per query**        | Low (load only matched refs)                           | 0            |
| **Architecture**                | Failure-mode workflow                                  | --           |
| **Diagnoses before generating** | Yes (Step 2)                                           | No           |
| **Output contract**             | Yes -- assumptions, tradeoffs, rollback                | No           |
| **Conditional references**      | EKS, GKE, AKS, OpenShift, GitOps, observability stacks | No           |
| **Security-first defaults**     | PSS restricted profile                                 | No           |
| **Good/bad examples**           | Yes (2 dedicated files)                                | No           |
| **Do/Don't checklist**          | Yes (dedicated file)                                   | No           |
| **Compliance coverage**         | NSA/CISA, OWASP K8s Top 10, CIS, Pod Security Standards | No           |
| **Hallucination prevention**    | Core design goal                                       | No           |
| **Cross-resource validation**   | Label/selector/port consistency checks                 | No           |
| **Helm/Kustomize guidance**     | Dedicated reference files                              | No           |
| **Policy engine integration**   | Kyverno and OPA/Gatekeeper patterns                    | No           |
| **License**                     | MIT                                                    | --           |

### Why Failure-Mode-First Matters for Kubernetes

The key insight is architectural. A static reference manual gives Claude information but never tells it _how to think_ about a problem. There's no diagnosis step, no risk assessment, and no structured output -- Claude reads the reference and generates whatever it thinks fits.

KubeShark takes the opposite approach. The core SKILL.md is a compact operational workflow. It forces Claude through a diagnostic sequence: capture context -> identify failure modes -> load _only_ the relevant references -> propose fixes with explicit risk controls -> validate -> deliver a structured output contract.

This matters for Kubernetes specifically because:

1. **Silent failures are common.** A Service with the wrong selector depl
````
