@synapta/skills 0.1.1 → 0.2.0

package/skills/deploy-k8s/docs/failure-modes/network-exposure.md

@@ -0,0 +1,98 @@
+# FM3: Network Exposure
+
+Kubernetes networking is flat by default. Every pod can reach every other pod on any port, across all namespaces. There is no firewall, no segmentation, no access control until you explicitly create NetworkPolicy resources. This default-open posture means a single compromised container can reach databases, internal APIs, and cloud metadata endpoints without restriction.
+
+## The Default-Open Problem
+
+Unlike traditional networks where firewalls deny traffic by default, Kubernetes starts with full connectivity. Installing a CNI plugin that supports NetworkPolicy (Calico, Cilium, Antrea) is necessary but not sufficient -- the plugin only enforces policies that exist. A namespace with zero NetworkPolicy objects allows all traffic regardless of the CNI plugin.
+
+The correct baseline is a default-deny policy in every namespace, followed by explicit allow rules for required communication paths.
+
+## Service Types and Exposure Risk
+
+| Type | Exposure | Risk level |
+|---|---|---|
+| `ClusterIP` | Internal only | Low -- reachable only within the cluster |
+| `NodePort` | Every node IP on a high port | High -- bypasses Ingress, no TLS, no auth |
+| `LoadBalancer` | Public IP via cloud provider | Critical -- directly internet-facing |
+| `ExternalName` | DNS alias to external service | Low -- no proxying, but DNS rebinding possible |
+
+LLMs frequently generate `LoadBalancer` or `NodePort` Services when `ClusterIP` is sufficient. Always default to `ClusterIP` and expose externally only through an Ingress controller with TLS termination.
+
+## The Silent Selector Mismatch
+
+The most frustrating Kubernetes networking bug produces no error, no warning, and no log entry. When a Service `selector` does not match any pod labels, the Service gets zero Endpoints. Traffic sent to the Service simply vanishes -- connections time out or receive connection refused errors.
+
+This happens because:
+- The pod label says `app: api-server` but the Service selector says `app: api` (typo).
+- The selector includes a version label that changes on deploy (e.g., `version: v2` in the selector, but the new pods have `version: v3`).
+- Labels are case-sensitive: `App: api-server` does not match `app: api-server`.
+
+Always verify with `kubectl get endpoints <service-name>` after any Service or Deployment change.
+
+## NetworkPolicy AND/OR Logic
+
+The most common NetworkPolicy mistake is confusing AND and OR semantics in `from`/`to` rules:
+
+- **Same list item = AND:** A `namespaceSelector` and `podSelector` in the same `from` entry must both match.
+- **Separate list items = OR:** Two separate `from` entries are unioned -- traffic matching either rule is allowed.
+
+Getting this wrong can either block legitimate traffic or open traffic to the entire cluster. A single misplaced hyphen in YAML changes the behavior completely.
+
+## Egress Policies and DNS
+
+A default-deny egress policy blocks all outbound traffic including DNS resolution. If you forget to allow DNS (port 53 UDP and TCP to kube-system), every service lookup fails and the application appears to have network connectivity issues when it actually has a policy misconfiguration.
+
+Always include a DNS egress rule when writing egress policies:
+
+```yaml
+egress:
+  - to:
+      - namespaceSelector:
+          matchLabels:
+            kubernetes.io/metadata.name: kube-system
+    ports:
+      - protocol: UDP
+        port: 53
+      - protocol: TCP
+        port: 53
+```
+
+## DNS Performance and ndots
+
+Kubernetes defaults to `ndots: 5`, meaning any hostname with fewer than 5 dots triggers search domain expansion. For a call to `api.stripe.com` (2 dots), the resolver first tries `api.stripe.com.production.svc.cluster.local`, then `api.stripe.com.svc.cluster.local`, then `api.stripe.com.cluster.local`, and finally the actual address. This multiplies DNS queries by 4-5x for every external call.
+
+Fix with `dnsConfig.options: [{name: ndots, value: "2"}]` or append a trailing dot to external hostnames (`api.stripe.com.`).
+
+## Lateral Movement After Compromise
+
+Without NetworkPolicy, an attacker who compromises a single pod can:
+1. Scan the entire cluster network to discover services.
+2. Access databases directly (bypassing application-level auth).
+3. Reach the cloud metadata endpoint (169.254.169.254) to steal IAM credentials.
+4. Pivot to other namespaces to access higher-privilege workloads.
+5. Exfiltrate data to external endpoints without restriction.
+
+NetworkPolicy is the primary control against lateral movement. It reduces the blast radius of any single compromise from "the entire cluster" to "the pods this workload is explicitly allowed to reach."
+
+## What LLMs Get Wrong
+
+1. **No NetworkPolicy at all.** The most common error. The generated manifests include Deployments and Services but no network segmentation.
+2. **Ingress-only policies.** Writing a policy with only ingress rules still allows unrestricted egress. Always specify both `policyTypes: [Ingress, Egress]`.
+3. **Forgetting DNS egress.** Blocking all egress without a DNS exception breaks all service discovery.
+4. **NodePort as default.** Generating `type: NodePort` when `ClusterIP` would suffice, exposing the service on every node.
+5. **Missing `ingressClassName`.** Omitting it in an Ingress resource relies on a default IngressClass that may not exist, causing silent 404s.
+6. **Wrong port mapping.** Confusing the Service `port`, `targetPort`, and Ingress backend `port.number`. The Ingress backend references the Service port, not the container port.
+7. **`hostNetwork: true` without justification.** Bypasses all NetworkPolicy enforcement entirely.
+
+## Real-World Impact
+
+Lateral movement is the primary attack vector in Kubernetes breaches. The 2022 Sysdig threat report found that 87% of container images contained a high or critical vulnerability, and the average time from initial compromise to lateral movement was under 10 minutes in clusters without NetworkPolicy.
+
+Network segmentation is not optional security hardening -- it is the minimum viable defense for any multi-service deployment.
+
+## Further Reading
+
+- [Network Policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/)
+- [KubeShark Security Hardening Guide](../guides/security-hardening.md)
+- [KubeShark Do/Don't Checklist](../examples/do-dont-checklist.md)

package/skills/deploy-k8s/docs/failure-modes/privilege-sprawl.md

@@ -0,0 +1,91 @@
+# FM4: Privilege Sprawl
+
+Privilege sprawl occurs when workloads accumulate more Kubernetes API access than they need. It compounds the impact of every other failure mode -- a compromised container with `cluster-admin` permissions turns a single vulnerability into a full cluster takeover. RBAC misconfigurations are silent, hard to audit, and rarely reviewed after initial setup.
+
+## RBAC Fundamentals
+
+Kubernetes RBAC has four resource types:
+
+- **Role**: grants permissions within a single namespace.
+- **ClusterRole**: grants permissions cluster-wide or across all namespaces.
+- **RoleBinding**: binds a Role (or ClusterRole) to subjects within one namespace.
+- **ClusterRoleBinding**: binds a ClusterRole to subjects across the entire cluster.
+
+The principle of least privilege means using namespace-scoped Roles unless the workload genuinely needs cluster-wide access. Most application workloads need zero Kubernetes API access at all.
+
+## Wildcard Permissions
+
+Rules containing `verbs: ["*"]`, `resources: ["*"]`, or `apiGroups: ["*"]` grant unrestricted access. A single wildcard rule can negate every other security control in the cluster. Wildcards appear frequently in quickstart guides and Helm chart defaults because they "just work" -- but they grant far more access than any workload needs.
+
+Always enumerate specific verbs (`get`, `list`, `watch`, `create`, `update`, `patch`, `delete`), specific resources (`pods`, `configmaps`, `deployments`), and specific API groups (`""`, `apps`, `batch`). Use `resourceNames` to restrict access to specific named resources when possible.
+
+## The Default ServiceAccount Problem
+
+Every namespace has a `default` ServiceAccount. Every pod that does not specify `serviceAccountName` uses it. Every pod that uses it shares the same identity. This means:
+
+- A single RoleBinding granting permissions to the `default` SA affects every pod in the namespace.
+- If any pod in the namespace is compromised, the attacker inherits whatever permissions the `default` SA has.
+- RBAC audit trails cannot distinguish between workloads using the same SA.
+
+The fix: create a dedicated ServiceAccount for every workload. Set `automountServiceAccountToken: false` on both the ServiceAccount and the Pod spec for workloads that never call the Kubernetes API (which is most of them).
+
+## automountServiceAccountToken
+
+By default, Kubernetes mounts a service account token into every pod at `/var/run/secrets/kubernetes.io/serviceaccount/token`. This token grants whatever permissions the SA has. For workloads that never call the Kubernetes API (web servers, batch processors, data pipelines), this token is pure attack surface.
+
+Setting `automountServiceAccountToken: false` on the pod spec removes the token mount entirely. For workloads that do need API access, use projected token volumes with explicit audience and expiration instead of the legacy static token.
+
+## Secrets Are Not Encrypted
+
+The most dangerous misconception about Kubernetes Secrets is that they are secure. They are not:
+
+- **Base64 is not encryption.** `kubectl get secret -o yaml` shows the value. `echo <value> | base64 -d` decodes it. Any user or ServiceAccount with `get secrets` RBAC in the namespace can read every secret.
+- **etcd stores secrets in plaintext by default.** Without explicit `EncryptionConfiguration`, secrets are stored unencrypted in the cluster's backing store.
+- **Environment variable injection exposes secrets.** Secrets injected via `env.valueFrom.secretKeyRef` are visible in `kubectl describe pod`, process listings (`/proc/<pid>/environ`), and crash dumps.
+
+The hardened approach:
+1. Mount secrets as files via `volumeMounts`, not environment variables.
+2. Enable etcd encryption at rest as a baseline.
+3. Use external secret management (External Secrets Operator with AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault) for production secrets.
+4. Use Sealed Secrets for secrets that must be stored in Git.
+
+## Token Projection for API Access
+
+When a workload genuinely needs to call the Kubernetes API, use bound service account token volumes instead of the default mount:
+
+```yaml
+volumes:
+  - name: kube-api-token
+    projected:
+      sources:
+        - serviceAccountToken:
+            audience: "https://kubernetes.default.svc"
+            expirationSeconds: 3600
+            path: token
+```
+
+Projected tokens are short-lived and audience-scoped, limiting the damage if the token is leaked.
+
+## What LLMs Get Wrong
+
+1. **Binding `cluster-admin` to workload ServiceAccounts.** The most dangerous mistake. Appears in quickstart-style outputs when the LLM does not know the specific permissions needed.
+2. **Using wildcards for convenience.** `verbs: ["*"]` and `resources: ["*"]` appear frequently because they avoid enumeration.
+3. **Omitting `serviceAccountName`.** The pod silently uses the `default` SA, sharing identity with every other pod in the namespace.
+4. **Leaving `automountServiceAccountToken` at default.** The token is mounted even when the workload never calls the API.
+5. **Injecting secrets as environment variables.** Using `env.valueFrom.secretKeyRef` instead of volume mounts.
+6. **Hardcoding secret values in manifests.** Plaintext passwords in `env.value` fields, committed to version control.
+7. **Treating base64 as encryption.** Generating a Secret resource and assuming the data is protected.
+
+## Real-World Impact
+
+- **Shopify Kubernetes bug bounty:** An attacker gained access to a pod with excessive RBAC permissions, then used `kubectl` from inside the pod to read secrets from other namespaces.
+- **Kubernetes CVE-2018-1002105:** A privilege escalation vulnerability in the API server. Clusters where workloads already had broad RBAC permissions experienced full compromise; clusters with least-privilege RBAC contained the blast radius.
+- **Uber breach (2022):** While not Kubernetes-specific, the pattern -- hardcoded credentials in source code -- is identical to the secrets-in-env antipattern that LLMs reproduce.
+
+Privilege sprawl is cumulative and invisible until exploitation. Every unnecessary permission is an expansion of the attack surface that persists indefinitely unless explicitly revoked.
+
+## Further Reading
+
+- [RBAC Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
+- [KubeShark Security Hardening Guide](../guides/security-hardening.md)
+- [KubeShark Do/Don't Checklist](../examples/do-dont-checklist.md)

package/skills/deploy-k8s/docs/failure-modes/resource-starvation.md

@@ -0,0 +1,85 @@
+# FM2: Resource Starvation
+
+Every container in a Kubernetes cluster shares finite CPU, memory, and disk. Without explicit resource requests and limits, workloads compete unpredictably -- a single runaway process can starve an entire node. Resource starvation is the most common cause of production instability in Kubernetes and the hardest to diagnose after the fact.
+
+## QoS Classes and Eviction Order
+
+Kubernetes assigns a Quality of Service class to every pod based on how its resource fields are configured. This class determines eviction priority when a node runs out of resources:
+
+| QoS Class | Condition | Eviction order |
+|---|---|---|
+| **Guaranteed** | Every container has `requests == limits` for both CPU and memory | Last evicted |
+| **Burstable** | At least one container has `requests != limits` | Middle |
+| **BestEffort** | No requests or limits on any container | First evicted |
+
+A pod with no `resources` block at all is BestEffort. Under node memory pressure, the kubelet kills BestEffort pods first, then Burstable pods exceeding their requests, and Guaranteed pods only as a last resort. Running BestEffort in production is never acceptable.
+
+## CPU Throttling: The Invisible Latency Killer
+
+CPU is a compressible resource -- when a container hits its CPU limit, the kernel's Completely Fair Scheduler (CFS) throttles it rather than killing it. This causes latency spikes that are invisible in standard metrics. A container with a 250m CPU limit that needs 300m for a request will pause mid-execution, adding unpredictable delays.
+
+Current best practice for most application workloads: set CPU requests but omit CPU limits. This allows bursting to available capacity without CFS throttling. Set CPU limits only when running in multi-tenant clusters that require hard fairness guarantees, or when Guaranteed QoS is specifically needed.
+
+## Memory: Always Set a Limit
+
+Memory is incompressible. When a container exceeds its memory limit, the kernel OOM-kills the process immediately. There is no throttling, no warning -- the process is terminated and the container restarts. Set memory limits 25-50% above observed p99 usage to absorb garbage collection spikes and temporary allocations.
+
+## LimitRange and ResourceQuota
+
+Namespace-level guardrails catch workloads that slip through without resource specifications:
+
+- **LimitRange** sets default requests/limits for containers that omit them, and enforces min/max bounds per container. Without a LimitRange, a single container can request all available resources on a node.
+- **ResourceQuota** caps aggregate resource consumption per namespace: total CPU, memory, pod count, PVC count. When a ResourceQuota exists, every pod must specify resources or admission is rejected.
+
+Both should be present in every production namespace. LimitRange provides sensible defaults; ResourceQuota prevents a single namespace from starving the rest of the cluster.
+
+## OOMKill Cascades
+
+A particularly dangerous pattern occurs when OOMKills cascade. Pod A exceeds its memory limit and is killed. Its traffic shifts to pods B and C, which now handle more load, consume more memory, and also get OOMKilled. Within seconds, the entire service is in `CrashLoopBackOff`. This is especially common with JVM workloads where heap sizing does not account for off-heap memory, native threads, and container overhead.
+
+## PodDisruptionBudgets
+
+Without a PDB, voluntary disruptions (node upgrades, autoscaler scale-downs, `kubectl drain`) can terminate all replicas simultaneously. A PDB with `maxUnavailable: 1` ensures at least N-1 replicas remain running during planned disruptions. Critical rules:
+
+- Never set `minAvailable` equal to `replicas` -- it blocks all voluntary disruptions including cluster upgrades.
+- The PDB selector must exactly match the pod labels. A mismatched selector silently protects nothing.
+- PDBs only protect against voluntary disruptions. Node crashes and OOMKills bypass PDB constraints.
+
+## HPA Pitfalls
+
+The Horizontal Pod Autoscaler scales replicas based on metrics, but misconfiguration causes more problems than it solves:
+
+- **Target utilization too high (90%):** No headroom for traffic spikes. By the time new pods start, the existing pods are overwhelmed.
+- **Target utilization too low (30%):** Wasteful. The cluster runs 3x the needed capacity.
+- **No scale-down stabilization:** HPA scales down aggressively by default. A brief traffic dip removes pods, then the next spike overwhelms the reduced fleet. Set `scaleDown.stabilizationWindowSeconds: 300`.
+- **HPA `minReplicas` below PDB `minAvailable`:** HPA scales down to a count that violates the disruption budget, causing node drains to block indefinitely.
+
+## Topology Spread and Anti-Affinity
+
+Three replicas on the same node provide zero high availability. A single node failure takes all of them down. Use `topologySpreadConstraints` to distribute pods across zones and nodes:
+
+- Zone-level spread with `whenUnsatisfiable: DoNotSchedule` prevents all replicas from landing in one availability zone.
+- Node-level spread with `whenUnsatisfiable: ScheduleAnyway` provides a soft preference that does not block scheduling in small clusters.
+
+## What LLMs Get Wrong
+
+1. **Omitting resources entirely.** The most common error. The pod becomes BestEffort and is evicted first under any pressure.
+2. **Round-number guessing.** `cpu: 1` and `memory: 1Gi` without profiling. Requests should reflect measured steady-state usage, not arbitrary values.
+3. **Setting CPU limits by default.** CFS throttling causes latency spikes. Omit CPU limits unless multi-tenancy or Guaranteed QoS requires them.
+4. **Memory limit equal to request.** Zero headroom means any spike triggers OOMKill. Allow 25-50% margin.
+5. **Forgetting PDB.** Multiple replicas without a PDB is false redundancy -- a node drain kills them all.
+6. **Topology spread missing.** Three replicas with no spread constraints may all schedule to the same node.
+
+## Real Incidents
+
+- **Datadog outage (2023):** A cascading OOMKill across monitoring agents caused loss of observability during a separate infrastructure incident, delaying diagnosis by hours.
+- **GitHub rate limiting regression:** CPU throttling on API servers caused p99 latency to spike from 50ms to 2s. Removing CPU limits restored performance immediately.
+- **Zalando postmortem:** A missing PDB allowed a cluster upgrade to drain all pods of a critical payment service simultaneously, causing a 15-minute outage.
+
+Resource management is not optimization -- it is correctness. A manifest without resource configuration is incomplete.
+
+## Further Reading
+
+- [Managing Resources for Containers](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/)
+- [Pod Quality of Service Classes](https://kubernetes.io/docs/concepts/workloads/pods/pod-qos/)
+- [KubeShark Good Patterns](../examples/good-patterns.md)

package/skills/deploy-k8s/docs/getting-started/installation.md

@@ -0,0 +1,152 @@
+# Installation
+
+KubeShark can be installed in three ways depending on your environment: direct clone (recommended), marketplace install, or per-project setup for Codex.
+
+---
+
+## Option 1: Direct Clone (Recommended)
+
+Clone the repository into your Claude Code skills directory. Claude Code auto-discovers skills in `~/.claude/skills/` -- no restart or configuration needed.
+
+### 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)
+
+```cmd
+git clone https://github.com/LukasNiessen/kubernetes-skill.git "%USERPROFILE%\.claude\skills\kubernetes-skill"
+```
+
+After cloning, the skill is active immediately. Claude Code reads `SKILL.md` on the next Kubernetes-related prompt.
+
+---
+
+## Option 2: Marketplace Install
+
+Claude Code includes a built-in plugin system with marketplace support. This avoids manual cloning.
+
+**Add the marketplace source and install:**
+
+```
+/plugin marketplace add LukasNiessen/kubernetes-skill
+/plugin install kubernetes-skill
+```
+
+**Or use the interactive manager:**
+
+1. Run `/plugin` in Claude Code.
+2. Switch to the **Discover** tab.
+3. Find KubeShark and install.
+
+The marketplace reads `.claude-plugin/marketplace.json` in the repository to register KubeShark as an installable plugin.
+
+---
+
+## Option 3: Codex Per-Project Setup
+
+Codex has no global skill system. Setup is per-project: clone the skill into your repository and reference it from `AGENTS.md`.
+
+**Step 1 -- Clone into your project:**
+
+```bash
+git clone https://github.com/LukasNiessen/kubernetes-skill.git .kubernetes-skill
+```
+
+**Step 2 -- Reference in AGENTS.md:**
+
+Create or edit `AGENTS.md` in your repository root and add:
+
+```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.
+```
+
+Codex will follow the workflow whenever it encounters Kubernetes tasks in the project.
+
+---
+
+## Updating
+
+KubeShark is a plain Git repository. Pull the latest changes to update:
+
+**macOS / Linux:**
+
+```bash
+cd ~/.claude/skills/kubernetes-skill && git pull
+```
+
+**Windows (PowerShell):**
+
+```powershell
+cd "$env:USERPROFILE\.claude\skills\kubernetes-skill"; git pull
+```
+
+**Codex projects:**
+
+```bash
+cd .kubernetes-skill && git pull
+```
+
+---
+
+## Uninstalling
+
+Remove the cloned directory to uninstall.
+
+**macOS / Linux:**
+
+```bash
+rm -rf ~/.claude/skills/kubernetes-skill
+```
+
+**Windows (PowerShell):**
+
+```powershell
+Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\skills\kubernetes-skill"
+```
+
+**Codex projects:**
+
+```bash
+rm -rf .kubernetes-skill
+```
+
+Also remove the corresponding section from `AGENTS.md` if you added one.
+
+**Marketplace installs:**
+
+```
+/plugin uninstall kubernetes-skill
+```
+
+---
+
+## Verifying Installation
+
+Confirm the skill is installed correctly by checking that `SKILL.md` exists:
+
+**macOS / Linux:**
+
+```bash
+ls ~/.claude/skills/kubernetes-skill/SKILL.md
+```
+
+**Windows (PowerShell):**
+
+```powershell
+Test-Path "$env:USERPROFILE\.claude\skills\kubernetes-skill\SKILL.md"
+```
+
+If the file exists, KubeShark is ready. You can also verify by asking Claude Code a Kubernetes question -- the response should follow the 7-step workflow and include an output contract with assumptions, failure modes, and rollback notes.

package/skills/deploy-k8s/docs/getting-started/quick-start.md

@@ -0,0 +1,115 @@
+# Quick Start
+
+Get KubeShark running in under two minutes.
+
+---
+
+## 1. Install
+
+```bash
+git clone https://github.com/LukasNiessen/kubernetes-skill.git ~/.claude/skills/kubernetes-skill
+```
+
+See the [Installation guide](installation.md) for Windows commands and alternative install methods.
+
+---
+
+## 2. Use It
+
+### Explicit invocation
+
+Prefix your prompt with `/kubernetes-skill` to invoke the skill directly:
+
+```
+/kubernetes-skill Create a production-ready Deployment for a Node.js API with autoscaling
+```
+
+```
+/kubernetes-skill Review my StatefulSet for security and reliability issues
+```
+
+### Automatic activation
+
+KubeShark activates automatically when Claude Code detects a Kubernetes-related task. No prefix needed:
+
+```
+Create a Helm chart for a PostgreSQL StatefulSet with backup CronJobs
+```
+
+```
+Review my deployment.yaml for security issues
+```
+
+Both invocation methods produce the same structured output.
+
+---
+
+## 3. What to Expect
+
+Every KubeShark response follows a **7-step workflow**:
+
+| Step | What happens |
+|------|-------------|
+| 1. Capture context | Records cluster version, distribution, namespace, environment, workload type |
+| 2. Diagnose failure modes | Identifies which of the 6 failure modes apply to your task |
+| 3. Load references | Pulls 1-2 targeted reference files (not the entire knowledge base) |
+| 4. Propose fix path | Recommends a solution with risk controls and runtime behavior notes |
+| 5. Generate artifacts | Produces YAML manifests, Helm charts, Kustomize overlays, or policies |
+| 6. Validate | Provides dry-run commands, schema validation, and consistency checks |
+| 7. Output contract | States assumptions, tradeoffs, validation plan, and rollback notes |
+
+The output contract at the end is the key differentiator. It makes every response auditable -- you can verify assumptions and check the rollback path before applying anything to your cluster.
+
+---
+
+## 4. Example Tasks
+
+KubeShark handles a wide range of Kubernetes work. Here are common task types to try:
+
+### Deployment creation
+
+```
+/kubernetes-skill Create a production Deployment for a Python Flask API with 3 replicas, resource limits, and an Ingress
+```
+
+### Security review
+
+```
+/kubernetes-skill Review this Deployment for security issues and harden it with proper security contexts, NetworkPolicies, and RBAC
+```
+
+### Helm chart generation
+
+```
+/kubernetes-skill Create a Helm chart for a Redis cluster with configurable replicas and persistent storage
+```
+
+### Kustomize overlay
+
+```
+/kubernetes-skill Build a Kustomize overlay structure with base, staging, and production variants for my microservice
+```
+
+### RBAC setup
+
+```
+/kubernetes-skill Create least-privilege RBAC for a monitoring service that needs read access to pods and metrics across all namespaces
+```
+
+### Troubleshooting
+
+```
+/kubernetes-skill My pods are stuck in CrashLoopBackOff with OOMKilled status. Here is my manifest -- diagnose and fix it.
+```
+
+### Probe configuration
+
+```
+/kubernetes-skill Add proper liveness, readiness, and startup probes for a Java Spring Boot app that takes 90 seconds to start
+```
+
+### CI pipeline validation
+
+```
+/kubernetes-skill Create a CI pipeline step that validates all manifests with kubeconform and checks for policy violations with Kyverno
+```

package/skills/deploy-k8s/docs/guides/helm-patterns.md

@@ -0,0 +1,71 @@
+# Helm Chart Best Practices
+
+Helm is the standard package manager for Kubernetes. KubeShark follows these conventions when generating or reviewing Helm charts. For full YAML examples and the LLM mistake checklist, see [references/helm-patterns.md](https://github.com/LukasNiessen/kubernetes-skill/blob/main/references/helm-patterns.md).
+
+## Chart.yaml
+
+Every chart must declare `apiVersion: v2` (mandatory for Helm 3), a SemVer `version` that bumps on every chart change, and an independent `appVersion` tracking the application release. The `type` field should be `application` or `library`. Include a concise `description` field.
+
+Key rules:
+
+- `version` follows SemVer and must change on every chart modification -- Helm repositories serve stale versions from cache if the version is not bumped
+- `appVersion` tracks the application release independently of the chart version
+- Declare sub-chart dependencies in `Chart.yaml` under `dependencies`, not in a separate `requirements.yaml`
+
+## values.yaml Structure
+
+Group values by resource type. Provide secure defaults that match the PSS restricted profile out of the box:
+
+- **image** -- repository, tag (defaults to `appVersion`), pullPolicy
+- **securityContext** -- `runAsNonRoot`, `allowPrivilegeEscalation: false`, `readOnlyRootFilesystem: true`, `capabilities.drop: ["ALL"]`
+- **resources** -- explicit requests and memory limits
+- **probes** -- liveness and readiness paths, ports, and initial delays
+- **ingress** -- disabled by default with `enabled: false`
+- **serviceAccount** -- `create: true`, blank name, empty annotations
+
+Document every section with `# --` comments so `helm-docs` can auto-generate documentation.
+
+## Template Helpers (_helpers.tpl)
+
+Define reusable named templates for `fullname`, `labels`, `selectorLabels`, and `serviceAccountName`. All templates should:
+
+- Truncate names to 63 characters (Kubernetes DNS label limit)
+- Support `nameOverride` and `fullnameOverride` values
+- Use `include` (not `template`) so output can be piped to `nindent`
+
+## Template Conventions
+
+- Use {% raw %}`{{- ... -}}`{% endraw %} whitespace trimming to prevent blank lines in rendered output.
+- Always pipe string values through {% raw %}`{{ .Values.foo | quote }}`{% endraw %}.
+- Use {% raw %}`{{ toYaml .Values.resources | nindent N }}`{% endraw %} for nested objects -- never render at column 0.
+- Wrap optional resources in {% raw %}`{{- if .Values.ingress.enabled }}`{% endraw %} conditionals.
+- Use {% raw %}`{{ required "message" .Values.key }}`{% endraw %} for values that must be supplied by the user.
+
+## Dependency Management
+
+Declare sub-charts in `Chart.yaml` under `dependencies`. Run `helm dependency update` to generate `Chart.lock`. Use `condition` or `tags` to make sub-charts optional. Commit both `Chart.yaml` and `Chart.lock` to version control.
+
+## Security Defaults
+
+Charts should ship with secure defaults out of the box. Users who need to relax security (e.g., for a CNI plugin that requires host networking) can override values explicitly, but the default path should produce a PSS-restricted-compliant workload.
+
+Key defaults to include in every chart's `values.yaml`:
+
+- Pod-level `securityContext` with `runAsNonRoot: true` and `seccompProfile: RuntimeDefault`
+- Container-level `securityContext` with `allowPrivilegeEscalation: false`, `readOnlyRootFilesystem: true`, and `capabilities.drop: ["ALL"]`
+- `automountServiceAccountToken: false` unless the workload calls the Kubernetes API
+
+## Testing Pipeline
+
+Run these checks in order during development and CI:
+
+1. **`helm lint ./chart`** -- catch syntax and structural errors
+2. **`helm template release-name ./chart -f values-prod.yaml`** -- render manifests locally
+3. **`kubeconform -kubernetes-version X.Y.0 -strict`** -- validate rendered output against target cluster schemas
+4. **`helm test release-name`** -- run in-cluster test pods post-install
+
+Integrate these steps into your CI pipeline so every chart change is validated before merge. The schema validation step (kubeconform) is especially important because `helm lint` does not validate against the Kubernetes API schema.
+
+## Common LLM Mistakes
+
+The most frequent Helm-specific errors LLMs produce include: missing {% raw %}`{{-`{% endraw %} whitespace control, omitting `| nindent N` on `toYaml` calls, forgetting to `quote` string values, hardcoding labels instead of using `include` helpers, not providing defaults for image tags, and not bumping the chart version. See the full checklist in the [reference file](https://github.com/LukasNiessen/kubernetes-skill/blob/main/references/helm-patterns.md#llm-mistake-checklist).