Transform monolithic Terraform configurations into reusable, maintainable modules following HashiCorp's module design principles and community best practices.
80
37%
Does it follow best practices?
Impact
84%
1.05xAverage score across 10 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./terraform/module-generation/skills/refactor-module/SKILL.mdQuality
Discovery
32%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description identifies a clear domain (Terraform module refactoring) but lacks the depth needed for reliable skill selection. It provides only a single high-level action without enumerating specific capabilities, and critically omits any 'Use when...' guidance that would help Claude know when to select this skill over others.
Suggestions
Add an explicit 'Use when...' clause with trigger terms like 'refactor Terraform', 'modularize infrastructure', 'break up Terraform config', 'create Terraform modules', 'tf module structure'.
List specific concrete actions such as 'extract child modules, define input variables and outputs, set up module composition, configure module sources, handle state moves during refactoring'.
Include common user-facing keywords and file extensions like '.tf files', 'infrastructure as code', 'IaC', 'module registry', and 'Terraform refactoring' to improve trigger term coverage.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | It names the domain (Terraform) and a key action (transform monolithic configurations into reusable modules), but doesn't list multiple specific concrete actions like creating variables.tf, outputs.tf, structuring child modules, handling state migration, etc. | 2 / 3 |
Completeness | It describes what the skill does (transform monolithic Terraform into modules) but has no explicit 'Use when...' clause or trigger guidance. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and the 'what' is also only partially described, so this scores a 1. | 1 / 3 |
Trigger Term Quality | Includes relevant keywords like 'Terraform', 'modules', and 'configurations', but misses common user variations such as 'refactor', 'tf modules', '.tf files', 'infrastructure as code', 'IaC', or 'module registry'. Users might say 'break up my Terraform' or 'refactor Terraform' which aren't captured. | 2 / 3 |
Distinctiveness Conflict Risk | It's fairly specific to Terraform modularization, which is a distinct niche, but could overlap with general Terraform skills, IaC refactoring skills, or code refactoring skills. The lack of explicit trigger terms makes conflict boundaries unclear. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
42%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill provides excellent, actionable HCL code examples covering the full module refactoring lifecycle, which is its strongest quality. However, it is severely bloated — explaining concepts Claude already understands, inlining content that should be in separate files, and duplicating content from other skills. The workflow has reasonable sequencing but lacks explicit validation checkpoints before destructive state migration operations.
Suggestions
Cut the content by at least 50%: remove 'Capability Statement', 'Prerequisites', 'Input Parameters' table, 'Revision History', and explanatory markdown blocks in the Analysis Phase that describe rather than instruct.
Replace the inlined testing section with a brief reference to the terraform-test skill: 'For testing, use skill terraform-test' with at most 2-3 lines of module-specific testing guidance.
Add an explicit validation checkpoint before state migration: 'STOP: Run terraform plan before any state migration. Proceed ONLY if the plan shows expected changes. Back up state with terraform state pull > backup.tfstate.'
Extract the module documentation template, refactoring patterns, and common pitfalls into separate referenced files (e.g., MODULE_DOC_TEMPLATE.md, PATTERNS.md) to improve progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~400+ lines. It explains concepts Claude already knows (what modules are, what encapsulation means, what prerequisites are needed), includes unnecessary sections like 'Capability Statement', 'Input Parameters' table, 'Revision History', and extensive module documentation templates. The testing section copies content from another skill verbatim rather than just referencing it. Much of this could be cut by 60-70%. | 1 / 3 |
Actionability | The skill provides fully executable HCL code examples throughout — complete before/after refactoring examples, state migration commands (both moved blocks and CLI), validation rules, and testing file structures. The code is copy-paste ready and covers the full transformation lifecycle. | 3 / 3 |
Workflow Clarity | The six execution steps are clearly sequenced (Analysis → Design → Transform → State Migration → Documentation → Testing), and the state migration section includes a validation step (terraform plan to verify no changes). However, there's no explicit validation checkpoint between the code transformation step and state migration — a critical gap since state migration is destructive. The 'Common Pitfalls' section on state migration errors partially addresses this but is separated from the workflow. | 2 / 3 |
Progressive Disclosure | The content is a monolithic wall of text with no bundle files to reference. Everything is inlined — the full before/after code examples, module documentation template, testing guidance, refactoring patterns, common pitfalls, and version control strategy. The testing section should reference the terraform-test skill rather than duplicating its content. The module documentation template and detailed patterns could easily be split into separate referenced files. | 1 / 3 |
Total | 7 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (539 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
43ca9b0
Table of Contents
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.