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

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

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 }}