---
title: "refactor-module skill: split Terraform code into modules"
canonical_url: https://cookiesforai.app/skills/hashicorp/refactor-module
last_updated: 2026-10-02T01:58:30+02:00
type: skill
summary: "refactor-module is HashiCorp's agent skill for turning a monolithic Terraform configuration into reusable modules, with typed interfaces, documentation, tests and a state migration that recreates no resources."
install: "npx skills add hashicorp/agent-skills --skill refactor-module"
related:
  - "https://cookiesforai.app/skills/antonbabenko/terraform-skill"
  - "https://cookiesforai.app/skills/hashicorp/terraform-policy"
  - "https://cookiesforai.app/skills/hashicorp/terraform-style-guide"
  - "https://cookiesforai.app/skills/hashicorp/terraform-test"
---

# Refactor module

refactor-module is HashiCorp's agent skill for turning a monolithic Terraform configuration into reusable modules, with typed interfaces, documentation, tests and a state migration that recreates no resources.

| Fact | Value |
|---|---|
| Publisher | HashiCorp (official, own GitHub account) |
| Source | https://github.com/hashicorp/agent-skills/tree/HEAD/plugins/terraform/skills/refactor-module |
| License | MPL-2.0 |
| Repository stars | 881 on 2026-10-02 |
| Skill name | refactor-module |
| Version | 0.0.1 (from its SKILL.md, https://github.com/hashicorp/agent-skills/blob/HEAD/plugins/terraform/skills/refactor-module/SKILL.md, read 2026-10-02) |
| Category | Infrastructure as code |
| Skill last changed | 2026-08-26 |
| Page updated | 2026-10-02 |
| Facts checked | 2026-10-02 |

## Install

Install this skill with the skills CLI:

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

Or, for Claude Code, add HashiCorp's plugin marketplace:

```
claude plugin marketplace add hashicorp/agent-skills
```

Then install the terraform plugin, which holds all 16 Terraform 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.

## Ask your coding agent

A skill can include scripts that run on your computer, so read its source first: https://github.com/hashicorp/agent-skills/tree/HEAD/plugins/terraform/skills/refactor-module

```text
Install the agent skill refactor-module from github.com/hashicorp/agent-skills.
```

## What it 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 it

- 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 it needs

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

## Which agents it works in

HashiCorp documents it for GitHub Copilot, Claude Code, Codex, Cursor, OpenCode, IBM Bob. The open skills CLI also installs it into 78 agents (listed with the CLI on 2026-10-01).

## License

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.

## Questions people ask

### Does HashiCorp have an agent skill that reviews terraform plan output?

No. On 2026-10-01 hashicorp/agent-skills held 20 skills, 16 for Terraform and 4 for Packer, and none is dedicated to reading or reviewing terraform plan output. The closest is terraform-test, which can run tests in plan mode against assertions you write.

### Can I copy this HashiCorp skill into my own repository?

Yes. The skill is MPL-2.0. You can copy and use it in any project, open or closed source. If you change its files and distribute them, the changed files must stay MPL-2.0 and be available as source; your own files are not affected.

## Related

### Related skills for infrastructure as code

- [Terraform skill](https://cookiesforai.app/skills/antonbabenko/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.
- [Terraform policy](https://cookiesforai.app/skills/hashicorp/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.
- [Terraform style guide](https://cookiesforai.app/skills/hashicorp/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.
- [Terraform test](https://cookiesforai.app/skills/hashicorp/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.