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 modularization) and a high-level action, but lacks the specificity of concrete sub-actions and critically omits any 'Use when...' guidance. It would benefit from listing specific operations and adding explicit trigger terms to help Claude distinguish this skill from general Terraform or infrastructure-as-code skills.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to refactor Terraform code, split a monolithic .tf file into modules, or improve Terraform project structure.'
List more specific concrete actions such as 'creates variables.tf, outputs.tf, and main.tf for each module; defines input variables and output values; sets up module versioning and source references.'
Include natural trigger term variations users might say: 'refactor terraform', 'terraform module structure', 'split terraform config', 'tf modules', 'infrastructure as code modularization'.
| 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, versioning, etc. | 2 / 3 |
Completeness | It describes what the skill does (transform monolithic Terraform configs into modules) but has no explicit 'Use when...' clause or trigger guidance, which per the rubric should cap completeness at 2, and the 'when' is entirely missing, warranting 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', 'module structure', 'terraform best practices', '.tf files', or 'infrastructure as code'. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on Terraform module refactoring is fairly specific, but it could overlap with general Terraform skills, IaC best practices skills, or code refactoring skills. The lack of explicit trigger terms increases conflict risk. | 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, executable HCL 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 referenced skills. The workflow has a dangerous gap between code transformation and state migration without an explicit validation checkpoint.
Suggestions
Reduce content by 50-60%: remove the Capability Statement, Prerequisites, Input Parameters table, Revision History, and the inline module documentation template (Claude knows how to write READMEs). Cut the testing section to just 'Use skill terraform-test' since it's already referenced.
Split into bundle files: move the full before/after code example into an EXAMPLES.md file, refactoring patterns into PATTERNS.md, and common pitfalls into PITFALLS.md, with clear one-level references from SKILL.md.
Add an explicit validation checkpoint between code transformation (Step 3) and state migration (Step 4): e.g., 'Run terraform plan BEFORE migration to establish baseline; verify module structure compiles without errors'.
Remove the analysis phase markdown bullets and replace with a concrete checklist or command (e.g., 'Run terraform graph | dot -Tsvg > deps.svg to visualize dependencies before refactoring').
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~400+ lines. It explains concepts Claude already knows (what modules are, what encapsulation means, basic Terraform patterns), includes unnecessary sections like 'Capability Statement', 'Input Parameters' table, 'Revision History', and 'Prerequisites' that add no actionable value. The module documentation template section is essentially a README template that Claude can generate without instruction. The testing section copies content from another skill verbatim rather than referencing it. | 1 / 3 |
Actionability | The skill provides fully executable HCL code examples throughout — complete before/after refactoring examples, working state migration commands (both moved blocks and CLI), validation rules, and concrete module structures. The code is copy-paste ready and covers the full transformation lifecycle. | 3 / 3 |
Workflow Clarity | The six execution steps provide a clear sequence, and the state migration section includes a validation step (terraform plan to verify no changes). However, the analysis phase is vague markdown bullets rather than concrete steps, and there's no explicit validation checkpoint between the code transformation step and state migration — a critical gap given that state migration is destructive. The success criteria checklist at the end is helpful but disconnected from the workflow. | 2 / 3 |
Progressive Disclosure | The content is a monolithic wall of text with no bundle files to offload detail into. The massive before/after code example, the full module documentation template, the testing section, and the refactoring patterns could all be separate referenced files. The testing section explicitly says 'Use skill terraform-test' but then proceeds to duplicate content inline anyway. No bundle structure exists to support progressive disclosure. | 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 | |
339a113
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.