appkit: Skill for Claude Code

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 current state file (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

**Identify Refactoring Candidates**
- Group resources by logical function
- Identify repeated patterns
- Map resource dependencies
- Detect configuration coupling
- Analyze variable usage patterns

**Complexity Assessment**
- Count resource relationships
- Measure variable propagation depth
- Identify cross-resource references
- Evaluate state migration complexity

2. Module Design

Interface Design

# Define clear input contract
variable "network_config" {
  description = "Network configuration parameters"
  type = object({
    cidr_block         = string
    availability_zones = list(string)
    enable_nat         = bool
  })

  validation {
    condition     = can(cidrhost(var.network_config.cidr_block, 0))
    error_message = "CIDR block must be valid IPv4 CIDR."
  }
}

# Define output contract
output "vpc_id" {
  description = "ID of the created VPC"
  value       = aws_vpc.main.id
}

output "private_subnet_ids" {
  description = "List of private subnet IDs"
  value       = { for k, v in aws_subnet.private : k => v.id }
}