refactor-module

Overview of refactor-module skill

What refactor-module does

The refactor-module skill helps turn a monolithic Terraform configuration into a reusable module with clearer inputs, outputs, encapsulation, and migration planning. It is aimed at refactoring work, not greenfield module design, and it is most useful when you already have live Terraform code that has grown too large to maintain safely.

Who should use it

Use the refactor-module skill if you manage Terraform that is hard to reuse, hard to test, or risky to change because logic, resources, and state handling are all mixed together. It is a good fit for platform engineers, infra maintainers, and reviewers who need a practical refactor-module guide for breaking a working stack into module boundaries without losing state context.

Why it is different

This refactor-module skill is decision-oriented: it expects a source configuration, a module name, a target abstraction level, and a state compatibility plan. That makes it more actionable than a generic “make this modular” prompt because it pushes the agent to consider interfaces, migration, and registry packaging instead of only rearranging files.

How to Use refactor-module skill

Install and point it at the right code

For refactor-module install, use the site’s skill installation flow for hashicorp/agent-skills, then target the Terraform configuration that actually needs refactoring. The skill is designed around source_directory, module_name, abstraction_level, preserve_state, and optional target_registry, so provide those values up front rather than asking for a vague cleanup.

Read the right files first

Start with SKILL.md to understand the workflow, then inspect any repository context that defines conventions, ownership, or release expectations. If your environment has adjacent docs or module standards, read them before running the skill so the output matches your repo’s patterns for naming, versioning, and state migration.

Turn a rough request into a usable prompt

A weak prompt says, “Refactor this Terraform into modules.” A stronger refactor-module usage prompt says, “Refactor source_directory=./infra/prod, create module_name=vpc, use abstraction_level=intermediate, and preserve state compatibility for an existing live environment.” Add the current pain point too, such as duplicated resources, unclear interfaces, or a future need to publish to a registry, because that changes how aggressive the refactor should be.

Use a workflow that reduces rework

First ask for an analysis of the current configuration, then ask for module boundaries, variables, outputs, and migration steps. If the first pass is too broad, tighten the scope by asking for only one subsystem at a time, such as networking or IAM, so the module design stays testable and the state transition plan stays credible.

refactor-module skill FAQ

Is refactor-module only for existing Terraform code?

Yes, the refactor-module skill is mainly for existing configurations that need to be decomposed into maintainable modules. If you are starting from scratch, a normal design prompt may be enough, but this skill is better when you already have resources, dependencies, and state to preserve.

What should I provide before using refactor-module?

At minimum, provide the source directory, a module name, and whether state compatibility must be preserved. If you have registry targets, naming standards, or restrictions on abstraction level, include them too; those details help the refactor-module skill avoid producing a design that is hard to adopt in your environment.

When is refactor-module the wrong choice?

Do not use it if you only need a small cleanup, a naming pass, or a one-off Terraform example. It is also a poor fit if you cannot share enough context about current resources or state, because module refactoring depends on dependency awareness and migration constraints.

How to Improve refactor-module skill

Give the skill stronger constraints

The best refactor-module results come from explicit boundaries: what belongs in the module, what must stay in root configuration, and what cannot change because of production state. If you leave those unstated, the model may over-abstract resources or suggest a migration path that is technically neat but operationally expensive.

Provide the current pain, not just the desired outcome

Tell the skill why the refactor matters: duplicate stacks, frequent drift, slow changes, or plans to publish internally. That helps the refactor-module skill optimize for the right tradeoff between reuse and simplicity, which is often the hardest decision in Terraform module work.

Check outputs for interface quality and migration realism

Review variables, outputs, naming, and dependency flow first, then validate whether the state migration plan matches how your infrastructure is actually deployed. If the first answer is too generic, iterate by asking for a narrower abstraction level or a more conservative state-preserving approach; those changes usually improve the final refactor-module guide more than asking for “more detail” alone.