ai-superpower/.ai/skills/helm/SKILL.md

name	description	category	impact
helm	Helm chart guidelines focusing on explicit resource naming over complex umbrellas. Use when creating, modifying, or reviewing Helm charts and Kubernetes manifests.	infra	medium

Helm Chart Development Guidelines

🎯 Purpose

Provide strict boundaries for Helm chart development, prioritizing IaC principles, explicit naming, and minimal configurations.

🚨 CRITICAL: If the task involves creating a ConfigMap, wiring subchart dependencies, defining values.yaml architecture, or debugging live cluster infrastructure, YOU MUST use the read_file tool to read .ai/skills/helm/REFERENCE.md BEFORE generating any code.

🚨 Prohibitions (Thou Shalt Not)

• NEVER hardcode namespace: in templates. Only use {{ .Release.Namespace }} or a required value.
• NEVER hardcode release names. Only use {{ .Release.Name }}.
• NEVER template values.yaml. It is static and does not evaluate {{ .Release.Namespace }} or any function.
• NEVER use | default in templates. Use hardcoded fallbacks or required with a descriptive message.
• NEVER put required defaults in values.yaml. If it's required by the deployer, it has no baseline in values.yaml.
• NEVER preemptively parameterize everything. Start hardcoded; only extract to values when explicitly requested.
• NEVER hide resource names using complex {{ include "fullname" . }} helpers in umbrella charts.

Workflows (Audit Checklist)

When reviewing or building a Helm project, actively check these:

1. grep -r "namespace:" templates/ — Flag anything not .Release.Namespace or a required value.
2. grep -r "required" templates/ — Verify that values.yaml does NOT contain these keys.
3. Compare .Values.* usages vs values.yaml keys — Flag unused keys.
4. Verify subchart dependencies use condition: booleans, not nested .enabled.
5. Check hooks for helm.sh/hook-weight (e.g. "10" for prereqs, "15" for components).

✅ / ❌ Examples

Explicit Resource Naming

# ❌ FORBIDDEN: Obfuscated by helpers
name: {{ include "mychart.fullname" . }}

# ✅ REQUIRED: Explicit and readable
name: {{ .Release.Name }}-keycloak

Namespace Injection

# ❌ FORBIDDEN: Hardcoded environment
metadata:
  namespace: production

# ✅ REQUIRED: Defer to deployer
metadata:
  namespace: {{ .Release.Namespace }}

Required vs Defaults

# ❌ FORBIDDEN: Default in template masks missing config
host: {{ .Values.global.domain | default "" }}

# ✅ REQUIRED: Fails fast and tells deployer exactly what file to edit
host: {{ required "global.domain is required in values.<env>.yaml" .Values.global.domain }}