# refactor-module

This skill turns a monolithic Terraform configuration into reusable modules with clear variables and outputs. Useful when one main.tf has grown too risky to touch.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 6400 installs · ★ 909
- Author: hashicorp
- License: MPL-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/hashicorp/agent-skills/tree/HEAD/plugins/terraform/skills/refactor-module/SKILL.md
- Updated: 2026-10-05
- HTML: https://affpapa.org/en/nevibecode/skills/refactor-module

## What it does

The skill reads your existing Terraform code and breaks it into modules following HashiCorp's design principles. It starts with analysis: resources get grouped by logical function, repeated patterns surface, dependencies get mapped, and the difficulty of moving state is assessed. Then comes interface design — input variables with validation, plus outputs.

After that the code is rewritten. Repeated resource blocks collapse into `for_each` and `locals`, and a root configuration calls the module through `source`. State migration is its own step: before writing `moved` blocks or `state mv` commands, the agent inspects current state with `terraform state list` and `terraform show -json` to match old resource addresses to new ones. That is where things break — if the addresses do not line up, `terraform plan` reports destroy-and-recreate instead of a move.

Inputs are the path to the configuration, the module name, and whether state compatibility must be preserved. Abstraction level is one of "simple", "intermediate" or "advanced", with intermediate as the default. You need access to state and a grasp of how your resources depend on each other; without that the migration cannot be planned.

## Requirements
- Works with: Terraform

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add hashicorp/agent-skills --skill refactor-module -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/refactor-module/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/refactor-module/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add hashicorp/agent-skills --skill refactor-module -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/refactor-module/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add hashicorp/agent-skills --skill refactor-module -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/refactor-module/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install hashicorp/agent-skills refactor-module
```

2. **Manually: put the files in place**
- File: `.github/skills/refactor-module/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add hashicorp/agent-skills --skill refactor-module -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/hashicorp/agent-skills --path plugins/terraform/skills/refactor-module
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/refactor-module/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add hashicorp/agent-skills --skill refactor-module -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/hashicorp/agent-skills/tree/HEAD/plugins/terraform/skills/refactor-module/SKILL.md

## When to use it
- split an oversized `main.tf` into modules with clear boundaries
- fold repeated resource blocks into one module using `for_each`
- define variables and outputs as an explicit module contract
- plan a state move that avoids recreating live resources
- separate resources sharing a lifecycle from cross-cutting concerns like tagging

## Example prompts
- refactor the config in `./infra` into a `vpc` module and keep state intact
- move subnets and the internet gateway into a `network` module, advanced abstraction
- plan the state migration for the new module and show me the `moved` blocks

## Similar
- [terraform](https://affpapa.org/en/nevibecode/plugins/terraform.md) — plugin · ★ 44635
- [powershell-module-architect](https://affpapa.org/en/nevibecode/agents/powershell-module-architect.md) — subagent · 183 installs
- [terraform-module-library](https://affpapa.org/en/nevibecode/skills/terraform-module-library.md) — skill · 15615 installs
- [terraform-skill](https://affpapa.org/en/nevibecode/skills/terraform-skill.md) — skill · 7400 installs
- [terraform-patterns](https://affpapa.org/en/nevibecode/skills/terraform-patterns.md) — skill · 617 installs
- [aws-well-architected-review](https://affpapa.org/en/nevibecode/skills/aws-well-architected-review.md) — skill · 84 installs

From the same set: [hashicorp/agent-skills](https://affpapa.org/en/nevibecode/by/hashicorp/agent-skills.md) — 20 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md