Agent skills
helm-chart-scaffolding

Agent skill

helm-chart-scaffolding

Design, organize, and manage Helm charts for templating and packaging Kubernetes applications with reusable configurations. Use when creating Helm charts, packaging Kubernetes applications, or implementing templated deployments.

View SKILL.md on GitHub Repository

Stars 163

Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/k8s-helm-charts-dev

SKILL.md

Helm Chart Scaffolding

Comprehensive guidance for creating, organizing, and managing Helm charts for packaging and deploying Kubernetes applications.

Purpose

This skill provides step-by-step instructions for building production-ready Helm charts, including chart structure, templating patterns, values management, and validation strategies.

When to Use This Skill

Use this skill when you need to:

Create new Helm charts from scratch
Package Kubernetes applications for distribution
Manage multi-environment deployments with Helm
Implement templating for reusable Kubernetes manifests
Set up Helm chart repositories
Follow Helm best practices and conventions

Chart Complexity Classification

Before starting, classify your chart to determine the appropriate approach:

Level	Characteristics	CI Handling	Example
Simple	Single container, no external deps, standard probes	Full lint + install	Static site, simple API
Standard	Multiple resources, ConfigMaps/Secrets, optional deps	Full lint + install	Web app with ingress
Complex	External services required, multi-port, JVM config	Lint only, skip install	OpenMetadata, data platforms
Operator	CRDs, webhooks, cluster-wide resources	Lint only, manual test	Prometheus Operator

Quick Decision:

Needs database/search/messaging at runtime? → Complex (exclude from install tests)
Has admin port separate from main port? → Check assets/patterns/multi-port-service.yaml
JVM application? → Check assets/patterns/jvm-application.yaml

Details: See references/chart-complexity.md for full classification guide and CI configuration.

Research Strategy

Before creating a chart, research the application:

Check for official chart - Many projects maintain their own Helm charts
Review Docker documentation - Container entrypoint, environment variables, ports
Identify external dependencies - What services does the app need?

If documentation scraping fails, use alternative methods:

Search GitHub for existing implementations
Check Docker Hub for environment variable documentation
Review Kubernetes deployment examples in project repos

Details: See references/research-strategy.md for complete fallback strategies and information gathering checklist.

Structured Development Workflow

For complex charts or when contributing to existing projects, use a structured approach:

Workflow Selection

Chart Complexity	Official Chart Exists	Workflow
Simple/Standard	No	Fast Path - Quick research, create, validate
Simple/Standard	Yes (use as-is)	Skip - Use existing chart
Complex/Operator	No	Full Workflow - Research → Plan → Implement
Any	Yes (extend)	Full Workflow with contribution strategy

Research Phase

Systematically investigate the application before creating templates:

Check for existing charts (official, community)
Gather configuration details (image, ports, env vars)
Document findings in structured format
Get approval for complex applications

Details: See references/research-phase-workflow.md

Planning Phase

Translate research into actionable implementation plan:

Create high-level plan with target features
Break down into atomic components (phases)
Draft phase plans for each component
Get sequential approvals
Map plans to GitHub issues (optional)

Details: See references/planning-phase-workflow.md

Implementation Phase

Execute with quality gates and review checkpoints:

Create worktree and draft PR immediately
Implement following phase plan
Run sanity checks (lint, template, security)
Pause for external review when needed
Submit PR when complete, clean up worktree

Details: See references/implementation-workflow.md

Extending Existing Charts

When an official chart exists but needs improvements:

Decide: fork repo vs copy locally
Review upstream patterns and values schema
Maintain compatibility for contribution
Document differences and improvements
Prepare upstream contribution (PR or patch)

Details: See references/extend-contribute-strategy.md

Helm Overview

Helm is the package manager for Kubernetes that:

Templates Kubernetes manifests for reusability
Manages application releases and rollbacks
Handles dependencies between charts
Provides version control for deployments
Simplifies configuration management across environments

Step-by-Step Workflow

1. Initialize Chart Structure

Create new chart:

bash

helm create my-app

Standard chart structure:

my-app/
├── Chart.yaml           # Chart metadata
├── values.yaml          # Default configuration values
├── charts/              # Chart dependencies
├── templates/           # Kubernetes manifest templates
│   ├── NOTES.txt       # Post-install notes
│   ├── _helpers.tpl    # Template helpers
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── serviceaccount.yaml
│   ├── hpa.yaml
│   └── tests/
│       └── test-connection.yaml
└── .helmignore         # Files to ignore

2. Configure Chart.yaml

Chart metadata defines the package:

yaml

apiVersion: v2
name: my-app
description: A Helm chart for My Application
type: application
version: 1.0.0      # Chart version
appVersion: "2.1.0" # Application version

# Keywords for chart discovery
keywords:
  - web
  - api
  - backend

# Maintainer information
maintainers:
  - name: DevOps Team
    email: devops@example.com
    url: https://github.com/example/my-app

# Source code repository
sources:
  - https://github.com/example/my-app

# Homepage
home: https://example.com

# Chart icon
icon: https://example.com/icon.png

# Dependencies
dependencies:
  - name: postgresql
    version: "12.0.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled
  - name: redis
    version: "17.0.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: redis.enabled

Reference: See assets/Chart.yaml.template for complete example

3. Design values.yaml Structure

Organize values hierarchically:

yaml

# Image configuration
image:
  repository: myapp
  tag: "1.0.0"
  pullPolicy: IfNotPresent

# Number of replicas
replicaCount: 3

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

# Ingress configuration
ingress:
  enabled: false
  className: nginx
  hosts:
    - host: app.example.com
      paths:
        - path: /
          pathType: Prefix

# Resources
resources:
  requests:
    memory: "256Mi"
    cpu: "250m"
  limits:
    memory: "512Mi"
    cpu: "500m"

# Autoscaling
autoscaling:
  enabled: false
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

# Environment variables
env:
  - name: LOG_LEVEL
    value: "info"

# ConfigMap data
configMap:
  data:
    APP_MODE: production

# Dependencies
postgresql:
  enabled: true
  auth:
    database: myapp
    username: myapp

redis:
  enabled: false

Reference: See assets/values.yaml.template for complete structure

4. Create Template Files

Use Go templating with Helm functions:

templates/deployment.yaml:

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "my-app.fullname" . }}
  labels:
    {{- include "my-app.labels" . | nindent 4 }}
spec:
  {{- if not .Values.autoscaling.enabled }}
  replicas: {{ .Values.replicaCount }}
  {{- end }}
  selector:
    matchLabels:
      {{- include "my-app.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "my-app.selectorLabels" . | nindent 8 }}
    spec:
      containers:
      - name: {{ .Chart.Name }}
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
        imagePullPolicy: {{ .Values.image.pullPolicy }}
        ports:
        - name: http
          containerPort: {{ .Values.service.targetPort }}
        resources:
          {{- toYaml .Values.resources | nindent 12 }}
        env:
          {{- toYaml .Values.env | nindent 12 }}

5. Create Template Helpers

templates/_helpers.tpl:

yaml

{{/*
Expand the name of the chart.
*/}}
{{- define "my-app.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}

{{/*
Create a default fully qualified app name.
*/}}
{{- define "my-app.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- if contains $name .Release.Name }}
{{- .Release.Name | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}
{{- end }}

{{/*
Common labels
*/}}
{{- define "my-app.labels" -}}
helm.sh/chart: {{ include "my-app.chart" . }}
{{ include "my-app.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{/*
Selector labels
*/}}
{{- define "my-app.selectorLabels" -}}
app.kubernetes.io/name: {{ include "my-app.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

6. Manage Dependencies

Add dependencies in Chart.yaml:

yaml

dependencies:
  - name: postgresql
    version: "12.0.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled

Update dependencies:

bash

helm dependency update
helm dependency build

Override dependency values:

yaml

# values.yaml
postgresql:
  enabled: true
  auth:
    database: myapp
    username: myapp
    password: changeme
  primary:
    persistence:
      enabled: true
      size: 10Gi

7. Test and Validate

Validation commands:

bash

# Lint the chart
helm lint my-app/

# Dry-run installation
helm install my-app ./my-app --dry-run --debug

# Template rendering
helm template my-app ./my-app

# Template with values
helm template my-app ./my-app -f values-prod.yaml

# Show computed values
helm show values ./my-app

Validation script:

bash

#!/bin/bash
set -e

echo "Linting chart..."
helm lint .

echo "Testing template rendering..."
helm template test-release . --dry-run

echo "Checking for required values..."
helm template test-release . --validate

echo "All validations passed!"

Reference: See scripts/validate-chart.sh

8. Package and Distribute

Package the chart:

bash

helm package my-app/
# Creates: my-app-1.0.0.tgz

Create chart repository:

bash

# Create index
helm repo index .

# Upload to repository
# AWS S3 example
aws s3 sync . s3://my-helm-charts/ --exclude "*" --include "*.tgz" --include "index.yaml"

Use the chart:

bash

helm repo add my-repo https://charts.example.com
helm repo update
helm install my-app my-repo/my-app

9. Multi-Environment Configuration

Environment-specific values files:

my-app/
├── values.yaml          # Defaults
├── values-dev.yaml      # Development
├── values-staging.yaml  # Staging
└── values-prod.yaml     # Production

values-prod.yaml:

yaml

replicaCount: 5

image:
  tag: "2.1.0"

resources:
  requests:
    memory: "512Mi"
    cpu: "500m"
  limits:
    memory: "1Gi"
    cpu: "1000m"

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 20

ingress:
  enabled: true
  hosts:
    - host: app.example.com
      paths:
        - path: /
          pathType: Prefix

postgresql:
  enabled: true
  primary:
    persistence:
      size: 100Gi

Install with environment:

bash

helm install my-app ./my-app -f values-prod.yaml --namespace production

10. Implement Hooks and Tests

Pre-install hook:

yaml

# templates/pre-install-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: {{ include "my-app.fullname" . }}-db-setup
  annotations:
    "helm.sh/hook": pre-install
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": hook-succeeded
spec:
  template:
    spec:
      containers:
      - name: db-setup
        image: postgres:15
        command: ["psql", "-c", "CREATE DATABASE myapp"]
      restartPolicy: Never

Test connection:

yaml

# templates/tests/test-connection.yaml
apiVersion: v1
kind: Pod
metadata:
  name: "{{ include "my-app.fullname" . }}-test-connection"
  annotations:
    "helm.sh/hook": test
spec:
  containers:
  - name: wget
    image: busybox
    command: ['wget']
    args: ['{{ include "my-app.fullname" . }}:{{ .Values.service.port }}']
  restartPolicy: Never

Run tests:

bash

helm test my-app

Common Patterns

Pattern 1: Conditional Resources

yaml

{{- if .Values.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ include "my-app.fullname" . }}
spec:
  # ...
{{- end }}

Pattern 2: Iterating Over Lists

yaml

env:
{{- range .Values.env }}
- name: {{ .name }}
  value: {{ .value | quote }}
{{- end }}

Pattern 3: Including Files

yaml

data:
  config.yaml: |
    {{- .Files.Get "config/application.yaml" | nindent 4 }}

Pattern 4: Global Values

yaml

global:
  imageRegistry: docker.io
  imagePullSecrets:
    - name: regcred

# Use in templates:
image: {{ .Values.global.imageRegistry }}/{{ .Values.image.repository }}

Pattern Templates

Ready-to-use patterns for common scenarios. Copy values and template sections to your chart.

External Services

Pattern	Use When	File
Database	Chart connects to MySQL or PostgreSQL	`assets/patterns/external-database.yaml`
Search	Chart connects to Elasticsearch or OpenSearch	`assets/patterns/external-search.yaml`
Messaging	Chart connects to Airflow, Kafka, RabbitMQ, or Redis	`assets/patterns/external-messaging.yaml`

All patterns include:

Values structure with existingSecret support
Helper template functions
Environment variable configuration
Example configurations

Application Architecture

Pattern	Use When	File
Multi-Port Service	App has main + admin/metrics ports	`assets/patterns/multi-port-service.yaml`
JVM Application	Java/Kotlin/Scala app needing heap/GC config	`assets/patterns/jvm-application.yaml`
Health Probes (Multi-Port)	Different probes on different ports	`assets/patterns/health-probes-multiport.yaml`

Quick Reference

For port numbers, environment variables, and connection strings:

references/external-services.md - Common services reference table

Best Practices

Use semantic versioning for chart and app versions
Document all values in values.yaml with comments
Use template helpers for repeated logic
Validate charts before packaging
Pin dependency versions explicitly
Use conditions for optional resources
Follow naming conventions (lowercase, hyphens)
Include NOTES.txt with usage instructions
Add labels consistently using helpers
Test installations in all environments

Troubleshooting

Template rendering errors:

bash

helm template my-app ./my-app --debug

Dependency issues:

bash

helm dependency update
helm dependency list

Installation failures:

bash

helm install my-app ./my-app --dry-run --debug
kubectl get events --sort-by='.lastTimestamp'

Reference Files

Chart Templates

assets/Chart.yaml.template - Chart metadata template
assets/values.yaml.template - Values structure template

Pattern Files

assets/patterns/external-database.yaml - MySQL/PostgreSQL configuration
assets/patterns/external-search.yaml - Elasticsearch/OpenSearch configuration
assets/patterns/external-messaging.yaml - Airflow/Kafka/RabbitMQ/Redis configuration
assets/patterns/multi-port-service.yaml - Multiple ports pattern
assets/patterns/jvm-application.yaml - JVM heap/GC/JMX configuration
assets/patterns/health-probes-multiport.yaml - Probes on different ports

Workflow Templates

assets/templates/research-summary.md - Research findings documentation
assets/templates/high-level-plan.md - High-level chart plan
assets/templates/phase-plan.md - Per-phase implementation plan
assets/templates/issue-structure.md - GitHub issue hierarchy

References

references/chart-structure.md - Detailed chart organization
references/chart-complexity.md - Chart complexity classification guide
references/research-strategy.md - Documentation research and fallback strategies
references/external-services.md - Common ports, env vars, connection strings
references/extend-contribute-strategy.md - Extending and contributing to existing charts
references/research-phase-workflow.md - Research phase structured workflow
references/planning-phase-workflow.md - Planning phase structured workflow
references/implementation-workflow.md - Implementation phase with checkpoints

Scripts

scripts/validate-chart.sh - Validation script

Related Skills

k8s-manifest-generator - For creating base Kubernetes manifests
gitops-workflow - For automated Helm chart deployments

Maintainer

majiayu000 Core maintainer

Source details

Full Name: majiayu000/claude-skill-registry
Branch: main
Path in repo: skills/data/k8s-helm-charts-dev
License: MIT License

Featured Tools

Join Our Newsletter

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

SKILL.md

Helm Chart Scaffolding

Purpose

When to Use This Skill

Chart Complexity Classification

Research Strategy

Structured Development Workflow

Workflow Selection

Research Phase

Planning Phase

Implementation Phase

Extending Existing Charts

Helm Overview

Step-by-Step Workflow

1. Initialize Chart Structure

2. Configure Chart.yaml

3. Design values.yaml Structure

4. Create Template Files

5. Create Template Helpers

6. Manage Dependencies

7. Test and Validate

8. Package and Distribute

9. Multi-Environment Configuration

10. Implement Hooks and Tests

Common Patterns

Pattern 1: Conditional Resources

Pattern 2: Iterating Over Lists

Pattern 3: Including Files

Pattern 4: Global Values

Pattern Templates

External Services

Application Architecture

Quick Reference

Best Practices

Troubleshooting

Reference Files

Chart Templates

Pattern Files

Workflow Templates

References

Scripts

Related Skills

Recommended Agent Skills

agent-ops-spec

agent-ops-state

agent-ops-spec

agent-ops-testing

agent-ops-testing

agent-ops-state