Use when writing, reviewing, or debugging Terraform/OpenTofu modules, tests, CI, scans, or state ops - diagnoses failure mode (identity churn, secrets, blast radius, CI drift, state corruption) with version-aware guards.

Terraform Skill for Claude Diagnose first guidance for Terraform and OpenTofu. Core file is a workflow; depth lives in references loaded on demand. Response Contract Every Terraform/OpenTofu response must include: 1. Assumptions & version floor — runtime ( terraform or tofu ), exact version, providers, state backend, execution path (local/CI/Cloud/Atlantis), environment criticality. State assumptions explicitly if the user did not provide them. 2. Risk category addressed — one or more of: identity churn, secret exposure, blast radius, CI drift, compliance gaps, state corruption, provider upgrade risk, testing blind spots. 3. Chosen remediation & tradeoffs — what was chosen, what was traded off, why. 4. Validation plan — exact commands ( fmt check , validate , plan out , policy check) tailored to runtime and risk tier. 5. Rollback notes — for any destructive or state mutating change: how to undo, what evidence to keep. Never recommend direct production apply without a reviewed plan artifact and approval. Never run terraform destroy (targeted or full) without first running terraform plan destroy and showing the user every resource that will be deleted — including implicit dependents pulled in via locals or for each . Get explicit confirmation before proceeding. Never use auto approve on destroy. Workflow 1. Capture execution context — runtime+version, provider(s), backend, execution path, environment criticality. 2. Diagnose failure mode(s) using the routing table below. If intent spans categories, load both references. 3. Load only the matching reference file(s) — do not preload depth the task does not need. 4. Propose fix with risk controls — why this addresses the mode, what could still go wrong, guardrails (tests/approvals/rollback). 5. Generate artifacts — HCL, migration blocks ( moved , import ), CI changes, policy rules. 6. Validate before finalizing — run validation commands tailored to risk tier. 7. Emit the Response Contract at the end. Diagnose Before You Generate Failure category Symptoms Primary references Identity churn Resource addresses shift after refactor, count index churn, missing moved blocks [Code Patterns: count vs for each](references/code patterns.md count vs for each deep dive), [Code Patterns: moved blocks](references/code patterns.md moved blocks terraform 11), [Code Patterns: LLM mistakes](references/code patterns.md llm mistake checklist code patterns) Secret exposure Secrets in defaults, state, logs, CI artifacts [Security & Compliance](references/security compliance.md), [Code Patterns: write only](references/code patterns.md write only arguments terraform 111), [State Management](references/state management.md) Blast radius Oversized stacks, shared prod/non prod state, unsafe applies [State Management](references/state management.md), [Module Patterns](references/module patterns.md) Destroy cascade Targeted destroy deletes more than expected; locals referencing a targeted resource make all for each consumers implicit dependents Response Contract: plan destroy first; [State Management: Safe Destroy](references/state management.md safe destroy protocol) CI drift Local plan ≠ CI plan, apply without reviewed artifact, unpinned versions [CI/CD Workflows](references/ci cd workflows.md), [Code Patterns: versions](references/code patterns.md version management) Compliance gaps Missing policy stage, no approval model, no evidence retention [Security & Compliance](references/security compliance.md), [CI/CD Workflows](references/ci cd workflows.md) Testing blind spots Plan only validation of computed values, set type indexing, mock/real confusion [Testing Frameworks](references/testing frameworks.md) State corruption / recovery Stuck lock, backend migration, drift reconciliation [State Management](references/state management.md) Provider upgrade risk Breaking change provider bump, unpinned modules [Code Patterns: versions](references/code patterns.md version management), [Module Patterns](references/module patterns.md) Provider lifecycle Removing a provider with resources still in state, orphaned resources, removed block usage [State Management: Provider Removal](references/state management.md provider removal) Bootstrap / orchestration misuse null resource + local exec for bootstrap, remote exec for setup scripts, provisioner stdout leaking secrets in CI logs [Code Patterns: Provisioners as Last Resort](references/code patterns.md provisioners as last resort) Navigation / safe rename blind spots Cannot locate symbol defs/refs semantically, value symbol rename done as blind text replace, grep only refactor missing refs, hallucinated rg shim [Code Intelligence](references/code intelligence lsp.md terraform ls capability matrix) Cross cloud / provider mapping "What's the Azure/GCP equivalent of X", picking a backend/auth model per cloud [State Management: Cross cloud equivalents](references/state management.md cross cloud equivalents) When to Use This Skill Activate when: creating or reviewing Terraform/OpenTofu configurations or modules, setting up or debugging tests, structuring multi environment deployments, implementing IaC CI/CD, choosing module patterns or state organization, configuring or migrating remote state backends. Don't use for: basic HCL syntax questions Claude already knows, provider API reference (link to docs), cloud platform questions unrelated to Terraform/OpenTofu. Core Principles Module Hierarchy Type When to Use Scope Resource module Single logical group of connected resources VPC + subnets, SG + rules Infrastructure module Collection of resource modules for a purpose Multiple resource modules in one region/account Composition Complete infrastructure Spans multiple regions/accounts Flow: resource → resource module → infrastructure module → composition. Directory Layout Separate environments from modules . Use examples/ as both documentation and test fixtures. Keep modules small and single responsibility. See [Module Patterns](references/module patterns.md) for architecture principles, naming conventions, variable/output contracts. Naming Conventions (summary) Descriptive resource names ( aws instance.web server , not aws instance.main ) Reserve this for genuine singleton resources only Prefix variables with context ( vpc cidr block , not cidr ) Standard files: main.tf , variables.tf , outputs.tf , versions.tf See [Module Patterns: Variable Naming](references/module patterns.md) and [Code Patterns: Block Ordering](references/code patterns.md block ordering structure) for examples. Block Ordering (summary) Resource blocks: count / for each first → arguments → tags → depends on → lifecycle . Variable blocks: description → type → default → validation → nullable → sensitive . See [Code Patterns: Block Ordering & Structure](references/code patterns.md block ordering structure) for the full rules and examples. Testing Strategy Decision Matrix: Which Testing Approach? Situation Approach Tools Cost Quick syntax check Static analysis validate , fmt Free Pre commit validation Static + lint validate , tflint , trivy , checkov Free Terraform 1.6+, simple logic Native test framework terraform test Free Low Pre 1.6, or Go expertise Integration testing Terratest Low Med Security/compliance focus Policy as code OPA, Sentinel Free Cost sensitive workflow Mock providers (1.7+) Native tests + mocks Free Multi cloud, complex Full integration Terratest + real infra Med High Native Test Rules (1.6+) Before writing test code: validate resource schemas via Terraform MCP so assertions target real attributes. command = plan — fast, for input derived values only command = apply — required for computed values (ARNs, generated names) and set type nested blocks Set type blocks cannot be indexed with [0] — use for expressions or materialize via command = apply Common set types: S3 encryption rules, lifecycle transitions, IAM policy statements See [Testing Frameworks](references/testing frameworks.md) for static analysis pipelines, native test patterns, Terratest integration, mock providers, and the full LLM mistake checklist. Count vs For Each — Quick Rule Scenario Use Why Boolean condition (create / don't) count = condition ? 1 : 0 Optional singleton toggle Items may be reordered or removed for each = toset(list) Stable resource addresses Reference by key for each = map Named access Multiple named resources for each Better identity stability Never use list index as long lived identity — removing a middle element reshuffles every address after it. For the decision matrix, safe migration playbook, moved block patterns, and known at plan failure cases, see [Code Patterns: count vs for each](references/code patterns.md count vs for each deep dive). Locals for Dependency Management Using try() in a local to prefer a conditional resource's attribute over its parent is a specialized but high value pattern — it forces correct deletion order without explicit depends on . Common use: VPC + secondary CIDR associations + subnets. See [Code Patterns: Locals for Dependency Management](references/code patterns.md locals for dependency management) for the full pattern and worked example. Module Development Standard layout: Variable contracts : always description , always explicit type , use validation for complex constraints, use sensitive = true for secrets, prefer optional() with typed defaults (1.3+) over untyped map(any) . Output contracts : always description , mark sensitive outputs, expose stable subsets (not whole provider objects). See [Module Patterns](references/module patterns.md) for the full contract patterns, module release checklist, and LLM mistake checklist. CI/CD Pipeline stages: validate → test → plan → apply (with environment protection). Cost control: mock providers on PR validation, real cloud integration only on main or scheduled, tag test resources, auto cleanup. Drift prevention: pin runtime and providers, commit .terraform.lock.hcl , apply the reviewed plan artifact from the plan stage (do not re run plan inside the apply job), run policy/security stage on every path to apply. See [CI/CD Workflows](references/ci cd workflows.md) for GitHub Actions, GitLab CI, and Atlantis templates plus the LLM mistake checklist. Security & Compliance Essential checks: Don't: store secrets in variables or .tfvars , use default VPC, skip encryption, open security groups to 0.0.0.0/0 , use inline ingress / egress blocks in aws security group . Do: source secrets from a cloud secret manager (AWS Secrets Manager / Azure Key Vault / GCP Secret Manager) or use write only arguments on 1.11+, create dedicated VPCs, enforce encryption at rest and TLS, least privilege SGs, use separate aws vpc security group {ingress,egress} rule resources (e.g. AWS provider v5+). Marking a variable sensitive = true masks display only — the value still lives in state. Use write only / wo on 1.11+, or keep secret material out of Terraform entirely via runtime lookups. See [Security & Compliance](references/security compliance.md) for trivy/checkov pipelines, state file hardening, compliance mappings, and the LLM mistake checklist. State Management Never use local state in teams or production. Remote backends provide automatic locking, encryption, versioning, audit logging, and safe collaboration. Choosing a Remote Backend AWS example (Azure azurerm / GCP gcs / TF Cloud syntax: see [State Manag

terraform-skill