Refactor Terraform into modules
Splits a monolithic Terraform configuration into a reusable module with a typed interface, then migrates state with moved blocks or terraform state mv so nothing is recreated. Use when a root config has grown too large or repeats itself.
refactor-module- Author
- HashiCorp
- Source
- hashicorp/agent-skills/plugins/terraform/skills/refactor-module @ 5e30fa5
- License
- MPL-2.0
About this skill
What it does
The skill moves resources from a monolithic Terraform configuration into a module without destroying and recreating them. It takes inputs — source_directory, module_name, abstraction_level (simple, intermediate or advanced), preserve_state and target_registry — and works in six steps.
Analysis groups resources by function, finds repeated blocks and maps dependencies. Design sets the module's contract: typed variables, objects where values belong together, validation rules, outputs. Coupled resources with one lifecycle go inside; tagging, monitoring and provider configuration stay outside. Once the code is rewritten, state migration starts with terraform state list and terraform show -json, then writes moved blocks (Terraform 1.1 and later) or terraform state mv commands for older versions, and warns that state holds secrets in plain text that must stay out of logs. The README follows a template with inputs and outputs tables, and testing hands over to the terraform-test skill.
It closes with three refactoring patterns (grouping, layering, composition), pitfalls such as map(map(any)) interfaces and modules that reference each other directly, and a success checklist whose last item is an empty plan after the refactor. The folder holds only SKILL.md.
When to use it, and when not
Use it when a root configuration has grown into one long main.tf, when the same resources are copied between environments, or before publishing code to a module registry.
It needs read access to the current state, which it lists with terraform state list. A new module written from scratch needs only the style guide.
How to run it
We do not copy this skill: its files are under MPL-2.0, a file-level copyleft licence outside the set we copy under. Install it from HashiCorp's repository with the button to the source: one skill via npx skills add hashicorp/agent-skills/plugins/terraform/skills/refactor-module, or the whole terraform plugin, in Claude Code claude plugin marketplace add hashicorp/agent-skills and claude plugin install terraform@hashicorp. In Codex: codex plugin marketplace add hashicorp/agent-skills, then install terraform from /plugins and start a new session. In Claude Code, the plugin's skill may appear as /terraform:refactor-module.
- Claude Code:
/refactor-module, or ask for the skill by name. - Codex:
$refactor-module. - Cursor: type
/in the Agent chat and pickrefactor-module.
Example: /refactor-module Move the VPC, subnets and internet gateway from main.tf into modules/vpc, keep the state with moved blocks and show me the plan.
How it differs from similar skills
Safe refactoring applies the same rule — structure changes, behavior does not — to application code: characterization tests first, one mechanical step per commit, tests after each step. Here the proof is different: moved blocks and a plan with no changes. Terraform style guide and Azure Verified Modules for Terraform are the rule sets the skill points to for the module itself, and Terraform tests covers the tests it asks for.
Install
This skill is not copied to the catalog: its licence allows a copy only under the same licence, and the catalog does not copy under such licences. Install it from the author's repository.
Connect through AnyModel API
This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.
AnyModel