Generates and standardizes README.md files for Terraform IaC projects (not reusable modules) following a consistent structure: title, overview, architecture, prerequisites, usage, inputs/outputs tables, CI pipeline, notes/caveats, contributing, and license. Use this skill whenever a user asks to create, write, scaffold, update, or improve a README for a Terraform project — even if they phrase it as "document this project", "add docs to this terraform config", "write a README for this IaC repo", or "what should a Terraform project README look like". Also trigger when the user shares .tf files or a project directory and asks for documentation. Produces terraform-docs-compatible tables for variable and output reference sections.
Auto-resolve: Before generating any output, derive
<repository-name>by runningbasename $(git rev-parse --show-toplevel)in the current working directory. Use the result everywhere<repository-name>appears below. Do not prompt the user for it.
<!-- AUTO-GENERATED by terraform-docs — do not edit manually --> <!-- AUTO-GENERATED by terraform-docs — do not edit manually -->Gist badge setup: Before writing the README, check whether the file
<repository-name>.jsonexists in gist476e6e7583432e960e6de16d5223e6a3by running:gh gist view 476e6e7583432e960e6de16d5223e6a3 --filesIf
<repository-name>.jsonis not listed, create it by writing a temporary file and adding it to the gist:
printf '{\n "schemaVersion": 1,\n "label": "status",\n "message": "in progress",\n "color": "yellow",\n "style": "flat"\n}' > /tmp/<repository-name>.json
gh gist edit 476e6e7583432e960e6de16d5223e6a3 --add /tmp/<repository-name>.json
Only then proceed to generate the README. The badge URL remains https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/bsubhamay/476e6e7583432e960e6de16d5223e6a3/raw/<repository-name>.json? regardless.
One-line summary of what this repository provisions.
Derive the overview by reading the repository's .tf files and CLAUDE.md
(if present). Write 3–5 sentences covering:
Do not repeat the title. Do not use generic placeholder text.
| Name | Version |
|---|---|
| terraform | >= 1.3.0 |
| aws | >= 5.0 |
Additional prerequisites:
ec2:*, iam:PassRoledns_support = true)| Name | Description | Type | Default | Required |
|---|---|---|---|---|
| name | Name prefix applied to all created resources | string | n/a | yes |
| cidr | CIDR block for the VPC | string | n/a | yes |
| azs | List of availability zones to deploy subnets into | list(string) | [] | no |
| private_subnets | List of CIDRs for private subnets | list(string) | [] | no |
| public_subnets | List of CIDRs for public subnets | list(string) | [] | no |
| enable_nat_gateway | Whether to create NAT Gateways for private subnets | bool | true | no |
| single_nat_gateway | Use a single shared NAT gateway instead of one per AZ | bool | false | no |
| tags | Map of tags to assign to all resources | map(string) | {} | no |
| Name | Description |
|---|---|
| vpc_id | The ID of the VPC |
| private_subnet_ids | List of IDs for private subnets |
| public_subnet_ids | List of IDs for public subnets |
| nat_gateway_ids | List of NAT Gateway IDs (empty when disabled) |
| vpc_cidr_block | The CIDR block of the VPC |
| Name | Type |
|---|---|
| aws_vpc.this | resource |
| aws_subnet.private | resource |
| aws_subnet.public | resource |
| aws_internet_gateway.this | resource |
| aws_nat_gateway.this | resource |
| aws_eip.nat | resource |
| aws_route_table.private | resource |
| aws_route_table.public | resource |
| aws_route_table_association.private | resource |
| aws_route_table_association.public | resource |
Destructive operation: Destroying this module will delete all subnets, route tables, and the VPC itself. Ensure no ENIs, load balancers, or RDS instances are attached before running
terraform destroy.
single_nat_gateway = true reduces cost but creates a single point
of failure for outbound internet traffic from private subnets.See CONTRIBUTING.md for full guidelines.
# Quick start
git clone [email protected]:org/terraform-aws-vpc.git
cd terraform-aws-vpc
terraform fmt -recursive
terraform validate
git checkout -b feat/ipv6-support)terraform fmt, terraform validate, and terraform-docs .test/ (Terratest)main with a clear description of changesThe Terratest job authenticates to GCP via Workload Identity Federation (service account impersonation). If the job fails with Permission 'iam.serviceAccounts.getAccessToken' denied, grant the WIF pool principal the required IAM binding:
gcloud iam service-accounts add-iam-policy-binding \
"<service-account-email>" \
--project="<gcp-project-id>" \
--role="roles/iam.workloadIdentityUser" \
--member="principalSet://iam.googleapis.com/projects/<project-number>/locations/global/workloadIdentityPools/<pool-name>/attribute.repository/<github-org>/<repository-name>"
The three repository variables required by the CI workflow are:
| Variable | Description |
|---|---|
GCP_PROJECT_ID | GCP project ID passed as GOOGLE_CLOUD_PROJECT to Terratest |
GCP_WORKLOAD_IDENTITY_PROVIDER | Full WIF provider resource name |
GCP_SERVICE_ACCOUNT | Service account email to impersonate |
MIT © 2026 Your Organization — see LICENSE for full terms.