helm

name	helm
description	Production-grade Helm 4 chart development, release management, and debugging. This skill should be used when users ask to create Helm charts, deploy with Helm, manage releases (install/upgrade/rollback), push charts to OCI registries, debug failed deployments, configure chart dependencies, create umbrella charts, set up GitOps with ArgoCD/Flux, or troubleshoot Helm issues. Auto-detects from Dockerfile/code, generates production-hardened charts with library patterns. Complements kubernetes skill.
hooks	{"PreToolUse":[{"matcher":"Bash","hooks":[{"type":"command","command":"bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/verify-helm-context.sh"}]}]}

Helm

Helm 4 chart development and operations with security-first defaults.

What This Skill Does

Chart Development:

• Creates production charts with library pattern (reusable base + thin apps)
• Generates templates, helpers, hooks, and dependencies
• Auto-detects from Dockerfile: ports, health endpoints, resources
• Supports umbrella charts for multi-service deployments
• Adds values schema validation (JSON Schema)

Release Management:

• Install, upgrade, rollback with atomic operations
• Release history and status inspection
• Values precedence management across environments
• Hook lifecycle (pre-install, pre-upgrade, post-upgrade, test)

Registry & Distribution:

• OCI registry workflows (push, pull, digest pinning)
• Chart versioning and artifact management
• GitOps integration (ArgoCD, Flux)

Debugging:

• Template rendering and debugging workflow
• Failed release recovery (stuck states, hook failures)
• Values resolution tracing
• Policy validation (OPA/Kyverno, security scanning)

What This Skill Does NOT Do

• Generate raw Kubernetes manifests (use kubernetes skill)
• Create Kustomize-only overlays without Helm
• Deploy Operators/CRDs (chart can include, but not operator setup)
• Manage cluster infrastructure (use kubernetes skill)
• Handle non-Helm deployments

---

Before Implementation

Source	Gather
Codebase	Dockerfile, existing charts, values patterns
Conversation	Target environment, chart name, special requirements
Skill References	Chart patterns, Helm 4 features, hooks, security
kubernetes skill	Manifest patterns for templates (complementary)

---

Required Clarifications

After auto-detection, confirm if ambiguous:

Question	When to Ask
Chart type	"Creating new chart, library chart, or umbrella chart?"
Target registry	"OCI registry (GHCR, ECR, Harbor) or Git repo for GitOps?"
Environment strategy	"Single values file or per-environment overlays (dev/staging/prod)?"
Release namespace	"Deploy to specific namespace or chart-managed?"

---

Helm 4 Defaults (CRITICAL)

Helm 4 introduces breaking changes from v3:

Feature	Helm 4 Behavior	Notes
Server-Side Apply	Default ON	Better conflict detection, GitOps alignment
kstatus watching	Accurate health	Replaces old --wait behavior
OCI-first	Native support	oci:// protocol, digest pinning
Wasm plugins	Sandboxed	Post-renderers require plugin format

See references/helm4-features.md for migration guidance.

---

Auto-Detection Matrix

From Dockerfile

Detect	How	Chart Generation
Port	EXPOSE	containerPort in deployment template
Health	CMD pattern	Liveness/readiness probe paths
User	USER instruction	securityContext.runAsUser
Base image	FROM	Resource hints (alpine=small, python=medium)

From Code

Detect	How	Chart Generation
Framework	imports/deps	Health endpoint patterns
GPU deps	torch, tensorflow	tolerations, nodeSelector, GPU resources
Sidecar needs	dapr.io, istio	Annotations for injection

---

Workflow

1. PRE-FLIGHT
   - Verify helm version (v4.x required)
   - Check target registry/cluster access
   - Identify existing charts
         ↓
2. ANALYZE PROJECT
   - Read Dockerfile for detection
   - Scan code for patterns
   - Check existing values patterns
         ↓
3. DETERMINE CHART TYPE
   - Application chart (default)
   - Library chart (reusable templates)
   - Umbrella chart (multi-service)
         ↓
4. GENERATE CHART
   - Chart.yaml with dependencies
   - values.yaml with schema
   - Templates with helpers
   - Hooks if lifecycle needs
         ↓
5. VALIDATE
   - helm lint
   - helm template --debug
   - helm install --dry-run
   - Policy validation (optional)
         ↓
6. DELIVER
   - Chart in charts/ directory
   - Summary of what was created
   - Next steps (push to registry, GitOps setup)

---

Chart Structure (Library Pattern)

charts/
├── myapp-lib/                    # Library chart (reusable)
│   ├── Chart.yaml                # type: library
│   ├── templates/
│   │   ├── _deployment.tpl       # Reusable deployment template
│   │   ├── _service.tpl          # Reusable service template
│   │   ├── _helpers.tpl          # Common helpers
│   │   └── _security.tpl         # Security context helpers
│   └── values.yaml               # Default values
│
└── myapp/                        # Application chart (thin)
    ├── Chart.yaml                # Dependencies: myapp-lib
    ├── templates/
    │   ├── deployment.yaml       # {{ include "myapp-lib.deployment" . }}
    │   ├── service.yaml          # {{ include "myapp-lib.service" . }}
    │   └── _helpers.tpl          # App-specific helpers
    ├── values.yaml               # App defaults
    ├── values.schema.json        # Schema validation
    └── values/                   # Environment overlays
        ├── dev.yaml
        ├── staging.yaml
        └── prod.yaml

---

Core Templates

Chart.yaml (Application)

apiVersion: v2
name: myapp
version: 0.1.0                    # Chart version (SemVer)
appVersion: "1.0.0"               # App version
type: application                 # or: library
description: |
  Brief description of what this chart deploys.

# Dependencies (subchart pattern)
dependencies:
  - name: myapp-lib
    version: ">=0.1.0"
    repository: "oci://ghcr.io/myorg/charts"
  - name: redis
    version: "17.x.x"
    repository: "oci://registry-1.docker.io/bitnamicharts"
    condition: redis.enabled      # Conditional dependency

# Kubernetes version constraint
kubeVersion: ">=1.25.0"

# Maintainers
maintainers:
  - name: DevRaftel
    email: [e-mail]

values.yaml (Structured)

# -- Number of replicas
replicaCount: 2

image:
  # -- Container image repository
  repository: myorg/myapp
  # -- Image pull policy
  pullPolicy: IfNotPresent
  # -- Image tag (defaults to appVersion)
  tag: ""

# -- Resource requests and limits
resources:
  requests:
    cpu: "100m"
    memory: "128Mi"
  limits:
    cpu: "500m"
    memory: "512Mi"

# -- Security context (pod level)
podSecurityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 1000

# -- Security context (container level)
securityContext:
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: true
  capabilities:
    drop: ["ALL"]

# -- Service configuration
service:
  type: ClusterIP
  port: 80
  targetPort: 8080

# -- Health probes
probes:
  liveness:
    path: /health/live
    initialDelaySeconds: 10
  readiness:
    path: /health/ready
    initialDelaySeconds: 5

# -- Enable autoscaling
autoscaling:
  enabled: false
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilization: 80

---

Command Reference

Chart Development

# Create new chart
helm create myapp

# Lint chart
helm lint ./myapp

# Render templates locally
helm template myapp ./myapp -f values.yaml

# Render with debug (shows template errors)
helm template myapp ./myapp --debug 2>&1 | head -100

# Package chart
helm package ./myapp

# Update dependencies
helm dependency update ./myapp
helm dependency build ./myapp

Release Management

# Install release
helm install myapp ./myapp -n namespace --create-namespace

# Install with atomic (rollback on failure)
helm install myapp ./myapp --atomic --timeout 5m

# Upgrade release
helm upgrade myapp ./myapp --atomic

# Upgrade or install
helm upgrade --install myapp ./myapp

# Rollback to previous
helm rollback myapp 1

# Uninstall
helm uninstall myapp -n namespace

# Release status
helm status myapp
helm history myapp

OCI Registry

# Login to registry
helm registry login ghcr.io -u USERNAME

# Push chart to OCI
helm push myapp-0.1.0.tgz oci://ghcr.io/myorg/charts

# Pull from OCI
helm pull oci://ghcr.io/myorg/charts/myapp --version 0.1.0

# Install from OCI
helm install myapp oci://ghcr.io/myorg/charts/myapp --version 0.1.0

Debugging

# Get release manifest
helm get manifest myapp

# Get computed values
helm get values myapp
helm get values myapp --all  # Including defaults

# Get hooks
helm get hooks myapp

# Dry-run against cluster
helm install myapp ./myapp --dry-run --debug

# Diff before upgrade (requires helm-diff plugin)
helm diff upgrade myapp ./myapp

---

Validation Pipeline

Before delivering charts, run:

# 1. Lint
helm lint ./myapp --strict

# 2. Template render
helm template myapp ./myapp --debug > /dev/null

# 3. Dry-run against cluster
helm install myapp ./myapp --dry-run --debug -n test

# 4. Schema validation (if values.schema.json exists)
helm lint ./myapp  # Automatically validates against schema

# 5. Policy validation (optional)
# OPA/Conftest
conftest test ./myapp/templates/

# Trivy for security scanning
trivy config ./myapp/

---

Output Checklist

Before delivering, verify:

Chart Structure

• Chart.yaml has apiVersion: v2, valid version, kubeVersion
• values.yaml has comments for helm-docs
• values.schema.json for validation
• Templates use _helpers.tpl for reusable definitions

Security

• securityContext in values with secure defaults
• No secrets in values.yaml (use external secrets)
• runAsNonRoot: true in pod security context
• Resource limits defined

Best Practices

• Labels follow app.kubernetes.io/* standard
• Health probes configurable via values
• Supports multiple environments (values overlays)
• Hooks have deletion policies

Validation

• helm lint passes without warnings
• helm template --debug renders successfully
• helm install --dry-run succeeds against cluster

GitOps Ready

• Chart versioned with SemVer
• OCI-pushable (no local dependencies)
• ArgoCD/Flux compatible structure

---

Reference Files

Always Read First

File	Purpose
references/chart-development.md	CRITICAL: Template syntax, helpers, hooks
references/values-patterns.md	CRITICAL: Precedence, environments, schema
references/helm4-features.md	CRITICAL: SSA, Wasm, kstatus, OCI

Operations

File	When to Read
references/release-management.md	Install, upgrade, rollback, atomic
references/oci-workflows.md	Push, pull, registry auth, digest
references/debugging-workflow.md	Template errors, failed releases
references/testing-validation.md	Lint, unittest, dry-run, integration tests

Integration

File	When to Read
references/gitops-integration.md	ArgoCD, Flux, ApplicationSet
references/umbrella-patterns.md	Multi-service, subcharts, Kustomize
references/ai-agent-patterns.md	GPU, models, sidecars, KEDA

Security & Compliance

File	When to Read
references/security-patterns.md	Secrets (ESO, Sealed), RBAC, policies
references/hooks-lifecycle.md	Hook types, weights, deletion policies