Skip to content
Terraform Style Guide

Terraform Style Guide Skill

HashiCorp's official skill for writing Terraform that matches the published style guide — file layout, naming, variable validation and secure-by-default resources.

GitHub Docs
DevOps & Infrastructure
Added to Onei AI
MPL-2.0

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from hashicorp/agent-skills.

$ npx skills add hashicorp/agent-skills --skill terraform-style-guide

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

  1. Open the skill on GitHub and download the folder that holds its SKILL.md.
  2. Put it at ~/.claude/skills/terraform-style-guide/, where Claude Code picks it up in every project.

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/terraform-style-guide/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • Canonical file layout across terraform.tf, providers.tf, main.tf, variables.tf, outputs.tf and locals.tf
  • Generates in dependency order: providers, data sources, resources, outputs
  • Two-space indentation and aligned assignments matching terraform fmt
  • Variables with types, descriptions and validation blocks
  • Secure-by-default resource configuration
  • Refactors count-based resources to for_each

HashiCorp publishes a Terraform Style Guide, and this skill is the machine-readable version of it: an agent loaded with this skill writes HCL that already conforms, instead of producing something plausible that a reviewer then has to correct line by line.

What it enforces

File organisation — the canonical split across terraform.tf (version constraints), providers.tf, main.tf, variables.tf, outputs.tf and locals.tf, with variables and outputs kept in alphabetical order.

Generation order — provider configuration and version constraints first, then data sources, then resources in dependency order, then outputs for the attributes anything downstream will need. Configurable values become variables rather than literals.

Formatting — two-space indentation, aligned equals signs within a block, and the conventions terraform fmt would apply anyway, produced correctly the first time.

Variable declarations — a type, a description and, where the value is constrained, a validation block with a usable error message rather than a failure five minutes into an apply.

Secure defaults — resources generated with encryption and access restrictions on by default, which is the difference between an S3 bucket that passes review and one that does not.

Where you would use it

Scaffolding a new module, auditing an inherited configuration for naming and structure violations, or refactoring count-based resources into for_each — the change that stops a removal in the middle of a list from re-creating everything after it.

Context

The skill lives in hashicorp/agent-skills under plugins/terraform/skills/, one of a set that also covers provider scaffolding, provider resources and actions, acceptance-test patterns, module refactoring, Terraform Stacks, and bulk-importing existing cloud resources into state. Licensed under MPL-2.0.

Try it

Once installed, ask your agent something like:

Audit this module against the HashiCorp Terraform style guide and fix what it flags.

SKILL.md

The instructions your agent loads, as published by HashiCorp.

SKILL.md
name
terraform-style-guide
description
Generate Terraform HCL code following HashiCorp's official style conventions and best practices. Use when writing, reviewing, or generating Terraform configurations.
metadata
lifecycle-status: active

Terraform Style Guide

Generate and maintain Terraform code following HashiCorp's official style conventions and best practices.

Reference: HashiCorp Terraform Style Guide

Code Generation Strategy

When generating Terraform code:

  1. Start with provider configuration and version constraints
  2. Create data sources before dependent resources
  3. Build resources in dependency order
  4. Add outputs for key resource attributes
  5. Use variables for all configurable values
File Organization
FilePurpose
terraform.tfTerraform and provider version requirements
providers.tfProvider configurations
main.tfPrimary resources and data sources
variables.tfInput variable declarations (alphabetical)
outputs.tfOutput value declarations (alphabetical)
locals.tfLocal value declarations
Example Structure
# terraform.tf
terraform {
  required_version = ">= 1.14"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"
    }
  }
}

# variables.tf
variable "environment" {
  description = "Target deployment environment"
  type        = string

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "Environment must be dev, staging, or prod."
  }
}

# locals.tf
locals {
  common_tags = {
    Environment = var.environment
    ManagedBy   = "Terraform"
  }
}

# main.tf
resource "aws_vpc" "main" {
  cidr_block           = var.vpc_cidr
  enable_dns_hostnames = true

  tags = merge(local.common_tags, {
    Name = "${var.project_name}-${var.environment}-vpc"
  })
}

# outputs.tf
output "vpc_id" {
  description = "ID of the created VPC"
  value       = aws_vpc.main.id
}
Code Formatting
Indentation and Alignment
  • Use two spaces per nesting level (no tabs)
  • Align equals signs for consecutive arguments
resource "aws_instance" "web" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
  subnet_id     = "subnet-12345678"

  tags = {
    Name        = "web-server"
    Environment = "production"
  }
}
Block Organization

Arguments precede blocks, with meta-arguments first:

resource "aws_instance" "example" {
  # Meta-arguments
  count = 3

  # Arguments
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"

  # Blocks
  root_block_device {
    volume_size = 20
  }

  # Lifecycle last
  lifecycle {
    create_before_destroy = true
  }
}
Naming Conventions
  • Use lowercase with underscores for all names
  • Use descriptive nouns excluding the resource type
  • Be specific and meaningful
  • Resource names must be singular, not plural
  • Default to main for resources where a specific descriptive name is redundant or unavailable, provided only one instance exists
# Bad
resource "aws_instance" "webAPI-aws-instance" {}
resource "aws_instance" "web_apis" {}
variable "name" {}

# Good
resource "aws_instance" "web_api" {}
resource "aws_vpc" "main" {}
variable "application_name" {}
Variables

Every variable must include type and description:

variable "instance_type" {
  description = "EC2 instance type for the web server"
  type        = string
  default     = "t2.micro"

  validation {
    condition     = contains(["t2.micro", "t2.small", "t2.medium"], var.instance_type)
    error_message = "Instance type must be t2.micro, t2.small, or t2.medium."
  }
}

variable "database_password" {
  description = "Password for the database admin user"
  type        = string
  sensitive   = true
}
Outputs

Every output must include description:

output "instance_id" {
  description = "ID of the EC2 instance"
  value       = aws_instance.web.id
}

output "database_password" {
  description = "Database administrator password"
  value       = aws_db_instance.main.password
  sensitive   = true
}
Dynamic Resource Creation
Prefer for_each over count
# Bad - count for multiple resources
resource "aws_instance" "web" {
  count = var.instance_count
  tags  = { Name = "web-${count.index}" }
}

# Good - for_each with named instances
variable "instance_names" {
  type    = set(string)
  default = ["web-1", "web-2", "web-3"]
}

resource "aws_instance" "web" {
  for_each = var.instance_names
  tags     = { Name = each.key }
}
count for Conditional Creation
resource "aws_cloudwatch_metric_alarm" "cpu" {
  count = var.enable_monitoring ? 1 : 0

  alarm_name = "high-cpu-usage"
  threshold  = 80
}
Security Best Practices

Refer to SECURITY.md. It includes guidance on encrypting resources,
preventing sensitive data in state, and secure configurations.

Version Pinning
terraform {
  required_version = ">= 1.14"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"
    }
  }
}

Use the latest major version of each provider and the latest minor version of
Terraform, unless otherwise constrained by a dependency lock file or by other
modules used by the configuration.

Version constraint operators:

  • = 1.0.0 - Exact version
  • >= 1.0.0 - Greater than or equal
  • ~> 1.0 - Allow rightmost component to increment
  • >= 1.0, < 2.0 - Version range
Provider Configuration
provider "aws" {
  region = "us-west-2"

  default_tags {
    tags = {
      ManagedBy = "Terraform"
      Project   = var.project_name
    }
  }
}

# Aliased provider for multi-region
provider "aws" {
  alias  = "east"
  region = "us-east-1"
}
Version Control

Never commit:

  • terraform.tfstate, terraform.tfstate.backup
  • .terraform/ directory
  • *.tfplan
  • .tfvars files with sensitive data

Always commit:

  • All .tf configuration files
  • .terraform.lock.hcl (dependency lock file)
Validation Tools

Run before committing:

terraform fmt -recursive
terraform validate

Additional tools:

  • tflint - Linting and best practices
  • checkov / tfsec - Security scanning
Code Review Checklist
  • [ ] Code formatted with terraform fmt
  • [ ] Configuration validated with terraform validate
  • [ ] Files organized according to standard structure
  • [ ] All variables have type and description
  • [ ] All outputs have descriptions
  • [ ] Resource names use descriptive nouns with underscores
  • [ ] Version constraints pinned explicitly
  • [ ] Sensitive values marked with sensitive = true
  • [ ] No hardcoded credentials or secrets
  • [ ] Security best practices applied

---

Based on: [HashiCorp Terraform Style Guide](https://developer.hashicorp.com/terraform/language/style)

Install
New

Microsoft's official skill for preparing apps for Azure with the Azure Developer CLI: writes a deployment plan first, then generates azure.yaml, Bicep or Terraform infrastructure and Dockerfiles before handing off to validation.

Skill: Azure Deploy

by Microsoft

New

Microsoft's official skill for executing Azure deployments of already-prepared apps: it checks for a validated deployment plan, runs azd up, azd deploy, terraform apply or az deployment with error recovery, then verifies endpoints and RBAC roles.

Browse all skills →