Kipt

Terraform module skill: HashiCorp's refactor-module for coding agents

HashiCorp's Terraform module skill, refactor-module, splits a monolithic config into reusable modules with moved blocks. What it does and how to install.

By the Kipt team · Updated 24 October 2026

Source: hashicorp/agent-skills · Maintainer: HashiCorp · License: MPL-2.0 · Checked: 24 October 2026

What is the refactor-module skill?

refactor-module is HashiCorp's official Agent Skill for turning a monolithic Terraform configuration into reusable modules. It gives Claude Code, Codex or another agent a step-by-step method: find the resources that belong together, design a clean interface, move the code, and migrate state without recreating infrastructure.

Its description reads: "Transform monolithic Terraform configurations into reusable, maintainable modules following HashiCorp's module design principles and community best practices."

It is one of 16 Terraform skills in hashicorp/agent-skills, next to the terraform-style-guide skill. On skills.sh it had about 6,300 installs (snapshot, 24 October 2026), third in the repo after terraform-style-guide and terraform-test.

What does it do?

The folder holds one SKILL.md of about 14,700 bytes, with frontmatter marking it lifecycle-status: active and version: "0.0.1".

It opens with input parameters the agent should establish: the source directory, a module name, an abstraction level (simple, intermediate or advanced), whether to preserve state compatibility, and a target registry (local, private or public). Then come six execution steps.

  1. Analysis. Group resources by function, spot repeated patterns, map dependencies and judge how hard the state migration will be.
  2. Module design. Define typed input variables with validation blocks and outputs with descriptions. Keep tightly coupled resources with a shared lifecycle together (a VPC and its subnets), and keep cross-cutting concerns such as monitoring and tagging separate.
  3. Code transformation. A worked before-and-after example turns hand-written aws_subnet.public_1 and public_2 resources into a modules/vpc module that uses for_each over availability zones, cidrsubnet() for addressing and merge() for tags, with separate main.tf, variables.tf and outputs.tf.
  4. State migration. Inspect current addresses with terraform state list and terraform show -json, then write moved blocks such as from = aws_vpc.main and to = module.vpc.aws_vpc.main. For Terraform older than 1.1 it gives the matching terraform state mv commands.
  5. Module documentation. A README template with overview, usage, requirements, inputs and outputs tables, and examples.
  6. Testing. Points to the terraform-test skill and summarizes test files, run blocks, assertions, mock providers, and plan versus apply mode.

After the steps come three refactoring patterns (resource grouping, configuration layering and composition), three pitfalls (over-abstraction with loose map(map(any)) types, tight coupling between modules, and untested state migrations), and a success checklist. The last two checklist items are the ones that matter most: "State migration completed without resource recreation" and "No plan differences after refactoring."

How does it line up with HashiCorp's own docs?

Mostly well. Three points from Terraform's documentation are worth knowing as you use it.

Topic What the skill says What Terraform's docs say
moved blocks Use them for state refactoring (Terraform 1.1+) Refactoring docs: v1.1 and later; "We strongly recommend that you retain all historical moved blocks"
When to make a module Avoid over-generic interfaces Module development docs: "We do not recommend writing modules that are just thin wrappers around single other resource types."
Versioning Example pairs a git:: source with a version constraint Module block docs: version "only applies when installing modules from a registry"; Git sources pin with ?ref=

The first two agree and add detail: keep your moved blocks after the migration, because removing one is a breaking change for anyone still on the old address. The third is a mismatch. Terraform treats any module block with a version argument as a registry module, so the example as written makes terraform init stop with an "Invalid registry module source address" error (Terraform source). Drop the version line and keep ?ref=v1.2.0 for Git, or use version with a registry source.

How do you install it?

One skill. The repo README uses the path form of the skills CLI:

npx skills add hashicorp/agent-skills/plugins/terraform/skills/refactor-module

skills.sh shows the equivalent npx skills add https://github.com/hashicorp/agent-skills --skill refactor-module. Add -g to install across projects. Because step 6 defers to terraform-test, add it too:

npx skills add hashicorp/agent-skills/plugins/terraform/skills/terraform-test

In Claude Code the folders land in .claude/skills/<name>/, or ~/.claude/skills/<name>/ with -g, per the Claude Code skills docs.

The Terraform bundle in Claude Code. From the README:

claude plugin marketplace add hashicorp/agent-skills
claude plugin install terraform@hashicorp

That installs all 16 Terraform skills, including refactor-module, terraform-test and terraform-style-guide. Plugin skills are namespaced, so this one appears as /terraform:refactor-module. The README says the bundle replaces older plugin IDs such as terraform-module-generation.

Codex and others. The README says to add the repo's .agents/plugins/marketplace.json as a repository marketplace and install the terraform plugin. Codex and Cursor also read the same SKILL.md format; see Codex skills and Cursor skills.

How do you use it?

Point it at a directory and say what you want to extract. It works best when you name the module and say whether existing infrastructure must stay untouched.

Example prompts (suggestions, not quotes from the repo):

  • Refactor ./infra/prod into a reusable vpc module. Preserve state: no resource may be recreated.
  • Find repeated patterns in this Terraform config and propose which modules to extract before changing anything.
  • Write the moved blocks for moving these subnets into module.network, using terraform state list for the current addresses.
  • Add typed variables with validation and a README with inputs and outputs tables to modules/database.
  • Add plan-mode tests for the new vpc module. (uses terraform-test)

Requirements: the Terraform CLI, with terraform init done so terraform show -json can render state. The skill's examples pipe that output through jq. No API keys, though reading remote state uses whatever backend credentials you already have.

Tips and limits

From the files and pages linked, not from testing:

  • Security audits. As of 24 October 2026, skills.sh showed Pass from Gen Agent Trust Hub (risk level SAFE), Socket and Snyk (risk level LOW), all audited 15 September 2026. Gen Agent Trust Hub tagged external downloads, command execution and indirect prompt injection, and noted that Terraform state files "frequently contain sensitive information", with the skill warning the agent not to output it.
  • State holds secrets. The skill itself says state "contains sensitive values in plaintext in every format" and tells the agent never to echo it into logs or output. Keep that in mind if your agent's transcripts are shared.
  • Always read the plan. The worked example's new subnets use cidrsubnet(var.cidr_block, 8, index(...)). With the example's 10.0.0.0/16 VPC, that gives 10.0.0.0/24 for the first zone (index 0), while the original public_1 used 10.0.1.0/24. A plan would show that difference. The skill's own advice covers it: apply only when the plan shows no changes.
  • Examples lean AWS. The code uses the AWS provider. The method carries over to other providers, and for Azure the skill links to the bundle's azure-verified-modules skill.
  • Version labels disagree. The frontmatter says 0.0.1; the revision history table at the bottom lists 1.0.0 from 7 November 2025.
  • License. MPL-2.0, a file-level copyleft: if you change these files and distribute them, share those files' source under MPL-2.0.

Save it in your Kipt library

In Kipt, open Skills and paste the refactor-module folder link into the import box. For a repo with many skills, Kipt shows a list to pick from, so you can take terraform-test and terraform-style-guide in the same pass. You can also drop the folder or a .zip, which is handy if you want to fix the versioning example or add your team's module naming rules first; under MPL-2.0, keep your changed files' source available if you share them. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with HashiCorp.

Similar skills

Questions

What is the refactor-module skill?

refactor-module is an Agent Skill in HashiCorp's hashicorp/agent-skills repo. It guides a coding agent through turning a monolithic Terraform configuration into reusable modules: analyzing resources, designing typed variables and outputs, rewriting the code, migrating state with moved blocks, documenting the module and adding tests.

How do I install HashiCorp's Terraform module skill?

For just this skill, run npx skills add hashicorp/agent-skills/plugins/terraform/skills/refactor-module. In Claude Code you can install all 16 Terraform skills with claude plugin marketplace add hashicorp/agent-skills and claude plugin install terraform@hashicorp.

Will refactoring into modules destroy my existing resources?

It should not if the state migration is right. The skill uses moved blocks, which Terraform 1.1 and later supports, so existing objects are treated as moved into the module instead of destroyed and recreated. It also tells you to run a plan and apply only if the plan shows no changes.

Does refactor-module write tests for the new module?

It covers testing at a high level and says to use the terraform-test skill for the details. Install terraform-test alongside it, or use the terraform plugin bundle, so the agent has the full guide to .tftest.hcl files, run blocks, assertions and mock providers.

Is the refactor-module skill safe to use?

As of 24 October 2026, skills.sh showed Pass from Gen Agent Trust Hub, Socket and Snyk, all audited 15 September 2026. The skill has no scripts, but it does ask the agent to read Terraform state, which can hold secrets in plaintext, so keep state output out of logs.

More in Skill directory

All guides

Keep your prompts and skills in one place, in your own GitHub. Install every skill with one command.

Get started

Kipt is an independent product, not affiliated with or endorsed by Anthropic, OpenAI, Cursor or GitHub. Claude, ChatGPT, Codex, Cursor and GitHub are trademarks of their owners.