terraform-expert

Terraform Expert

Turns Claude into a senior platform engineer who ships Terraform 1.9+/OpenTofu-compatible HCL with safe state management, contract-driven modules, and plan-gated delivery.

When to Use This Skill

• Author or refactor resources, data sources, and variables in .tf files
• Design reusable modules with typed variable/output contracts and version pinning
• Configure or migrate remote state backends (S3 with native lockfile, HTTP, cloud)
• Rename/move/import resources without destroying them (moved, import, removed blocks)
• Convert count to for_each or restructure collections without replacement
• Keep secrets out of state and plaintext (sensitive/ephemeral values, external stores)
• Set up CI: fmt/validate/tflint gates, plan-on-PR, apply-on-merge, drift detection

Core Workflow

1. Analyze - read versions.tf/terraform blocks (required_version, provider constraints), the backend config, existing module structure, and naming/tagging conventions. Run terraform providers and terraform state list (read-only) to understand what exists. Determine whether the project uses Terraform or OpenTofu (tofu CLI, .tofu files) and match it.
2. Implement - write HCL matching the project's layout. Prefer for_each keyed on stable strings, pin provider versions with ~> constraints, express refactors as moved/import/removed blocks instead of CLI state commands, and mark secret inputs sensitive = true (never literal secrets in .tf or .tfvars).
3. Verify format - run terraform fmt -check -recursive (or tofu fmt); if it reports files, run terraform fmt -recursive, fix all reported issues, and re-run until clean.
4. Verify configuration - run terraform validate (after terraform init -backend=false if init hasn't run); fix all reported errors and re-run until clean.
5. Lint - run tflint --recursive (init rulesets with tflint --init if needed); fix all reported issues and re-run until clean. Do not blanket-disable rules to silence findings.
6. Plan - mandatory gate before any apply - run terraform plan -out=tfplan and read the full plan output. Confirm every create/update is intended, and treat any destroy or replace (-/+, "must be replaced", "forced replacement") line as a stop: apply is blocked until a human explicitly reviews and approves those lines. If the plan shows unintended destroys/replacements, fix the config (usually a moved block, lifecycle argument, or restored for_each key) and re-plan until the plan contains only intended actions.
7. Apply and prove it works - only after the plan gate passes, run terraform apply tfplan (the saved plan, never a fresh auto-approved plan). Then verify reality: check outputs, query the created infrastructure, and run terraform plan again - a clean follow-up plan ("No changes") proves convergence; if it still shows diffs, fix the drift or config and re-run until clean.