From terraform
Terraform/HCL style conventions for writing readable, reusable modules — collection types, resource naming, name_prefix, for_each toggles, variable and output grouping, null defaults, and canonical file layout. Use when writing, reviewing, or refactoring Terraform code (.tf files, modules, root configurations), or when deciding how to name resources, structure variables, or shape module outputs.
How this skill is triggered — by the user, by Claude, or both
Slash command
/terraform:terraform-styleThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Apply these conventions to every module and root configuration; match them when editing existing
Apply these conventions to every module and root configuration; match them when editing existing code. They are load-bearing for readability and call-site ergonomics, not cosmetic preferences. For the rationale behind each rule and extended examples, see reference.md.
set(string) for unordered, unique itemsUse set(string) (not list(string)) whenever elements must be unique and order is irrelevant —
subnet IDs, instance types, CIDRs, ARNs, repository names, regions, namespaces. Uniqueness becomes
intrinsic, for_each gets stable keys without toset(), and the type documents intent.
variable "private_subnet_ids" {
description = "Private subnet IDs the cluster spans."
type = set(string)
}
Reserve list(...) for genuinely ordered data or where duplicates are meaningful. Terraform
auto-converts a set to a list when an argument requires one.
thismain (aws_eks_cluster.main).for_each/count resource → a singular noun for one element (aws_ecr_repository.repo).aws_iam_openid_connect_provider.irsa,
aws_ecr_lifecycle_policy.retention).The name should read well at the reference site, not echo the resource type
(aws_eks_node_group.node_group is redundant; .main is not).
name_prefix over nameFor resources whose name is unique within an account/region (IAM roles and policies, instance
profiles, security groups, launch templates, target groups), use name_prefix with a trailing -.
The provider appends a random suffix, so two stacks — or a create-before-destroy replacement —
never collide on a hard-coded name.
resource "aws_iam_role" "node" {
name_prefix = "${var.cluster_name}-node-" # good: stands up twice without a clash
}
# avoid: name = "${var.cluster_name}-node"
Keep the prefix ≤ 38 chars: the AWS random suffix is 26 and IAM role names cap at 64.
for_each, not countGate a resource on a boolean with for_each over a one-or-zero-element set, keeping a stable
address instead of a positional index:
resource "aws_iam_role" "node_windows" {
for_each = toset(var.enable_windows_nodes ? ["true"] : [])
# referenced as aws_iam_role.node_windows["true"].arn — not [0]
}
Reserve count for genuine cardinality (N identical resources).
Outputs read as module.<name>.<output>, so a concept prefix duplicates the module name at every
call site. Name the output for the attribute it exposes:
output "endpoint" { value = aws_eks_cluster.main.endpoint } # module.cluster.endpoint
# avoid: output "cluster_endpoint" → module.cluster.cluster_endpoint
Prefer one object variable over a cluster of flat scalars that are always configured together.
Give every attribute optional(type, default) and the variable default = {} so module "x" {}
still works and callers set only what they need:
variable "endpoint_access" {
description = "Cluster API endpoint exposure."
type = object({
private = optional(bool, true)
public = optional(bool, false)
public_cidrs = optional(set(string), [])
})
default = {}
}
Group only what is genuinely cohesive — unrelated knobs stay flat.
When several outputs are facets of one concept and would share a prefix (oidc_arn, oidc_url),
fold them into a single object output named for the concept:
output "node_role" {
description = "IAM role shared by worker nodes."
value = {
arn = aws_iam_role.node.arn
name = aws_iam_role.node.name
}
}
A primary resource's own top-level attributes (name, arn, endpoint) stay flat.
null over empty-string defaultsNever default an optional string to "". Use default = null for a flat variable, or
optional(string) with no second argument for an object attribute — null is the unambiguous
"unset" signal. Consumers absorb the null with coalesce(var.proxy.http, "") or compact([...]).
Provider and required_version constraints live in terraform.tf — never versions.tf. A module
consists of terraform.tf, main.tf, variables.tf, outputs.tf, README.md, plus optional
domain-specific files (iam-*.tf). Every variable and output carries a description.
To scaffold a new module with this layout, use the terraform-module skill; before committing,
run the terraform-validate workflow.
npx claudepluginhub bitwise-media-group/skills --plugin terraformGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.