terraform-module
Writes a Terraform module someone else can call without reading its insides: typed inputs that reject bad values at plan time, defaults that are safe if nobody changes them, and a README that says what goes in and what comes out. The module is a reusable building block, not a root configuration with a provider and backend baked in. Reviewing the plan it produces before apply is terraform-plan-review. Analysing the security of the wider system is threat-model.
How to respond
Get the need, the cloud and the callers, asking once for what is missing. Three inputs matter: what the infrastructure is for ("a bucket for ALB access logs, kept a year"), which provider (AWS, Google Cloud, Azure), and who calls the module (one team, many teams, a registry). Ask for any that are missing in one message, at most two questions. Default everything else and state the defaults at the top of the output: Terraform
>= 1.5.0, the current major version of the provider as a bounded range, one module per logical resource group.Lay out the standard module structure. Always produce these files, even when one is short:
versions.tf:required_versionandrequired_providerswithsourceand a boundedversionconstraint. ✅version = ">= 5.0, < 7.0"or"~> 5.40". ❌ no constraint, or">= 5.0"with no upper bound, which lets a breaking major version in on the nextinit.variables.tf: every input.main.tf: resources, data sources andlocals.outputs.tf: every value a caller needs, each with adescription.<module>/examples/basic/main.tf: a working call to the module with a provider block, using placeholder names.README.md: purpose, usage snippet, inputs table, outputs table, and what it creates. Usetemplates/module-readme.md. Noproviderblock and nobackendblock inside the module. The caller owns region, credentials and state.
Type and validate every variable. Each variable gets
type,descriptionand, where a bad value is possible, avalidationblock with anerror_messagethat tells the caller how to fix it. ✅type = numberplusvalidation { condition = var.retention_days >= 1 ... }. ❌type = any, or a string that silently takes "ture". Preferobject({...})withoptional()over loose maps for structured input. Checks that span two variables go in a resourcelifecycle { precondition { ... } }, which works on every supported Terraform version. Patterns are inreference.md.Make the defaults the secure choice. A caller who sets only the required inputs gets: encryption at rest on, public access off, TLS required, deletion protection or
force_destroy = falseon anything stateful, versioning or backups on where the service has them, and IAM statements scoped to named actions and resources. Each insecure option is an explicit opt-in variable with a description that says what it opens. ✅force_destroydefaultfalse. ❌acl = "public-read"as a default,Action = "*"in a policy,0.0.0.0/0ingress by default. The per-cloud checklist is inreference.md.Tag everything through one variable. Add
variable "tags"of typemap(string), default{}, merge it over a small set of module defaults inlocals(merge(local.default_tags, var.tags), so caller values win) and applylocal.tagsto every resource that supports tags. On Google Cloud the equivalent islabels, which must be lowercase.Hard-code nothing environment-specific. No account IDs, project IDs, subscription IDs, regions, ARNs, passwords, keys or tokens in the module. Look up the current account or project with a data source (
aws_caller_identity,google_client_config,azurerm_client_config), take secrets assensitive = truevariables or references to a secret manager, and mark outputs that carry secretssensitive = true.Tell the user how to check it. The skill writes files; it does not claim they pass checks it did not run. If
terraformis onPATH, say to runterraform init -backend=falseandterraform validatein the module, and run them if the session allows shell commands. Always end with the commands to run before merging:terraform fmt -recursive terraform init -backend=false && terraform validate terraform plan # from the basic example folder, against a sandbox accountAdd
tflintandcheckov -d .if the user's team uses them. Recommend running the resulting plan throughterraform-plan-reviewbefore the first apply.Emit the module in one message: the stated defaults and assumptions, then each file in its own fenced block headed by its path, then the check commands. Follow the shape of
examples/s3-log-bucket/.
Non-interactive runs (subagent, CI, headless): a missing provider version, Terraform version or naming scheme becomes a tagged [assumption] listed first. A missing cloud provider or a need too vague to name a resource ("some infrastructure for the app") emits BLOCKED: need the cloud provider and what the module must create. Never guess the cloud.
Useful references in this skill
reference.md: secure defaults per cloud, variable validation patterns, version constraint rules, tagging and labelling, and the secrets checklisttemplates/module-readme.md: the README skeleton with inputs and outputs tablesexamples/s3-log-bucket.md: the worked example, the input prompt and the decisions behind the moduleexamples/s3-log-bucket/: the module itself, withversions.tf,variables.tf,main.tf,outputs.tf, a basic usage example and its README
Quality bar
- All six pieces exist:
versions.tf,variables.tf,main.tf,outputs.tf, a basic usage example, and a README with inputs and outputs tables that match the code. - Provider and Terraform versions are constrained, with an upper bound on the provider major version.
- Every variable has a type and a description; every variable that can take a bad value has a validation block with a fixable error message.
- Defaults are secure: encryption on, public access off, least-privilege IAM, stateful resources protected from accidental destroy. Insecure options are opt-in variables.
- Tags flow from one
tagsvariable merged with module defaults onto every taggable resource. - No hard-coded secrets, account IDs, project IDs, regions or ARNs in the module.
- No provider or backend block inside the module.
- The output does not claim the module was validated unless the commands were actually run, and it shows their real output when they were.
When to use this skill
- ✅ "Write a Terraform module for a private S3 bucket / RDS instance / GCS bucket / VNet"
- ✅ Turning copy-pasted resource blocks from several root configs into one reusable module
- ✅ Scaffolding a module with sensible secure defaults before the team fills in details
- ✅ Adding validation, tagging and a README to an existing module that has none
When NOT to use this skill
- ❌ Reviewing a
terraform planbefore apply: useterraform-plan-review - ❌ Reviewing someone's Terraform pull request for bugs: use
pre-merge-review - ❌ Modelling the threats to the system the infrastructure supports: use
threat-model - ❌ Estimating what the infrastructure will cost at expected load: use
capacity-cost-model - ❌ Moving existing infrastructure or data from one platform to another: use
migration-plan
Anti-patterns to avoid
- ❌ A provider block inside the module. It pins the region and credentials for every caller and stops the module being used with provider aliases.
- ❌
type = anyand no validation. The first sign of a typo is a failed apply half an hour later instead of a plan-time error. - ❌ Unbounded provider versions.
version = ">= 4.0"builds today and breaks on the next major release, on someone else's machine. - ❌ Secure options as opt-in.
encrypted = falseas the default with a variable to turn it on means most callers never do. - ❌ Hard-coded account IDs and ARNs. The module works in one account and fails or, worse, grants access to the wrong one everywhere else.
- ❌ Tags set resource by resource. Half the resources end up untagged, and cost reports can't attribute them.
- ❌ A README that drifts from the code. An inputs table missing two variables is worse than none, because callers trust it.
- ❌ "Validated" without running anything. Saying the module passes
terraform validatewhen no one ran it.