Name: refactor-module
Author: hashicorp

Transform monolithic Terraform configurations into reusable, maintainable modules following HashiCorp's module design principles and community best practices.

Skill: Refactor Module Overview This skill guides AI agents in transforming monolithic Terraform configurations into reusable, maintainable modules following HashiCorp's module design principles and community best practices. Capability Statement The agent will analyze existing Terraform code and systematically refactor it into well structured modules with: Clear interface contracts (variables and outputs) Proper encapsulation and abstraction Versioning and documentation Testing frameworks Migration path for existing state Prerequisites Existing Terraform configuration to refactor Understanding of resource dependencies Access to inspect current state via terraform state list / terraform show json (for migration planning) Knowledge of module registry patterns Input Parameters Parameter Type Required Description source directory string Yes Path to existing Terraform configuration module name string Yes Name for the new module abstraction level string No "simple", "intermediate", "advanced" (default: intermediate) preserve state boolean Yes Whether to maintain state compatibility target registry string No Target module registry (local, private, public) Execution Steps 1. Analysis Phase 2. Module Design Interface Design Encapsulation Strategy 3. Code Transformation Before: Monolithic Configuration After: Modular Structure 4. State Migration Inspecting Current State Before writing moved blocks or state mv commands, inspect the current state to map existing resource addresses. Prefer the documented, stable, and more token efficient commands over reading the raw state file: terraform show json requires providers to be installed ( terraform init ), since it renders values against provider schemas. Fall back to the raw state ( terraform state pull / terraform.tfstate ) only when providers aren't available and init can't run, you need only coarse info (addresses, outputs, serial / lineage ), or you must avoid executing Terraform. Avoid parsing the raw version 4 state format as a stable interface. Note: state contains sensitive values in plaintext in every format — never echo state contents into logs or output. Generate Migration Plan Manual State Migration (Pre 1.1) 5. Module Documentation 6. Testing Use skill terraform test Test File : A .tftest.hcl or .tftest.json file containing test configuration and run blocks that validate your Terraform configuration. Test Block : Optional configuration block that defines test wide settings (available since Terraform 1.6.0). Run Block : Defines a single test scenario with optional variables, provider configurations, and assertions. Each test file requires at least one run block. Assert Block : Contains conditions that must evaluate to true for the test to pass. Failed assertions cause the test to fail. Mock Provider : Simulates provider behavior without creating real infrastructure (available since Terraform 1.7.0). Test Modes : Tests run in apply mode (default, creates real infrastructure) or plan mode (validates logic without creating resources). File Structure Terraform test files use the .tftest.hcl or .tftest.json extension and are typically organized in a tests/ directory. Use clear naming conventions to distinguish between unit tests (plan mode) and integration tests (apply mode): Refactoring Patterns Pattern 1: Resource Grouping Extract related resources into cohesive modules: Networking (VPC, Subnets, Route Tables) Compute (ASG, Launch Templates, Load Balancers) Data (RDS, ElastiCache, S3) Pattern 2: Configuration Layering Pattern 3: Composition Common Pitfalls 1. Over Abstraction 2. Tight Coupling 3. State Migration Errors Always test migration in non production first: Version Control Strategy Success Criteria [ ] Module has single, well defined responsibility [ ] All variables have descriptions and types [ ] Validation rules prevent invalid configurations [ ] Outputs provide sufficient information for consumers [ ] Documentation includes usage examples [ ] Tests verify module behavior [ ] State migration completed without resource recreation [ ] No plan differences after refactoring Related Skills [Terraform code generation](https://raw.githubusercontent.com/hashicorp/agent skills/refs/heads/main/plugins/terraform/skills/terraform style guide/SKILL.md) Style guide for the new Terraform Module [Azure Verified Modules](https://raw.githubusercontent.com/hashicorp/agent skills/refs/heads/main/plugins/terraform/skills/azure verified modules/SKILL.md) Recommended module specifications for Azure Resources [Terraform Module Development](https://developer.hashicorp.com/terraform/language/modules/develop) [Module Best Practices](https://developer.hashicorp.com/terraform/cloud docs/registry/design) Revision History Version Date Changes 1.0.0 2025 11 07 Initial skill definition