refactor-module

Install Refactor module

npx skills add hashicorp/agent-skills --skill refactor-module

claude plugin marketplace add hashicorp/agent-skills

claude plugin install terraform@hashicorp

In Codex, HashiCorp's README says to add the repository's .agents/plugins/marketplace.json as a repository marketplace, then install the terraform plugin.

Or paste this into your coding agent: Install the agent skill refactor-module from github.com/hashicorp/agent-skills. A skill can include scripts that run on your computer, so read its source first.

What Refactor module does

refactor-module is an agent skill from HashiCorp that walks an agent through breaking a large Terraform configuration into modules. It starts with analysis: grouping resources by function, finding repeated patterns, mapping dependencies and judging how hard the state migration will be. It then designs each module's interface as typed variables with validation and a set of outputs, and decides what belongs inside a module and what stays outside.

State migration is the risky step, and refactor-module handles it explicitly. The agent lists current addresses with terraform state list or terraform show -json rather than parsing the raw state file, and never echoes state contents, since they hold secrets in plain text. It writes moved blocks for Terraform 1.1 and newer, or terraform state mv commands for older versions, then checks that a plan shows no changes before anything is applied.

The skill also covers module documentation, testing through the terraform-test skill, semantic versioning for modules, and three refactoring patterns: grouping, layering and composition. It warns against over-generic modules and against modules that reference each other directly. Its success criteria include one responsibility per module and no resource recreation after the move.

When to use Refactor module

• Your Terraform lives in one large main.tf with copied blocks for each subnet or environment.
• You want to turn existing resources into a module without destroying and recreating them.
• You need moved blocks or terraform state mv commands written for a refactor.
• You want a reusable internal module with documented inputs and outputs.

When to pick something else

• Reviewing the output of terraform plan before an apply: HashiCorp's 20 skills (read 2026-10-01) include none made only for that job.
• Writing a module from scratch with no existing state: terraform-style-guide is enough.

What Refactor module needs

• Terraform CLI and read access to the current state (terraform state list); moved blocks need Terraform 1.1 or newer

Which agents Refactor module works in

HashiCorp documents Refactor module for GitHub Copilot, Claude Code, Codex, Cursor, OpenCode, IBM Bob. The open skills CLI also installs it into 78 agents, including Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode (we listed it with the CLI on October 1, 2026). See where each agent looks for skills.

Refactor module license

Refactor module is published under MPL-2.0. MPL-2.0 is a file-level copyleft license: you can use and copy the skill in any project, including closed source ones, but if you distribute changed versions of its files, those files stay under MPL-2.0 and must be shared as source.

Related skills for infrastructure as code

• Terraform skill: terraform-skill is Anton Babenko's agent skill for writing, testing and reviewing Terraform and OpenTofu, which names the risk before it writes code and never recommends a production apply without a reviewed plan. (2,394 repository stars on October 2, 2026)
• Terraform policy: terraform-policy is HashiCorp's agent skill for writing Terraform Policy files (.policy.hcl), testing them with .policytest.hcl, and converting Sentinel policies to the new format. (881 repository stars on October 2, 2026)
• Terraform style guide: terraform-style-guide is HashiCorp's agent skill for writing and reviewing Terraform HCL to the official style conventions: file layout, formatting, naming, typed variables, version pinning and a review checklist. (881 repository stars on October 2, 2026)
• Terraform test: terraform-test is HashiCorp's agent skill for writing and running Terraform's built-in tests: .tftest.hcl files with run blocks, assertions, expected failures, mock providers and CI pipelines. (881 repository stars on October 2, 2026)

Lists that include refactor-module

• Agent skills that do not depend on one agent