refactor-module
Transform monolithic Terraform configurations into reusable, maintainable modules following HashiCorp's module design principles and community best practices.
80
41%
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-tasks and critically omits any 'Use when...' trigger guidance. It would benefit from listing specific actions (e.g., extracting resources, creating variable/output definitions, structuring module directories) and adding explicit trigger terms users would naturally use.
Suggestions
Add a 'Use when...' clause with trigger terms like 'refactor Terraform', 'modularize infrastructure', 'split Terraform config', 'create Terraform module', or 'organize .tf files'.
List specific concrete actions such as 'extract resources into child modules, define input variables and outputs, structure module directories, update state references, and add module documentation'.
Include common user-facing keywords like 'HCL', 'infrastructure as code', 'IaC', '.tf files', and 'terraform refactor' 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 configs into modules) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, missing 'Use when' caps completeness at 2, and the 'what' is also only moderately detailed, warranting a 1. | 1 / 3 |
Trigger Term Quality | Includes relevant keywords like 'Terraform', 'modules', and 'configurations', but misses common user terms like 'refactor', 'terraform module', '.tf files', 'infrastructure as code', 'IaC', 'modularize', or 'HCL'. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on Terraform module refactoring is fairly specific and unlikely to conflict with most skills, but could overlap with general Terraform skills or infrastructure-as-code skills without clearer trigger boundaries. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
50%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 showing a complete before/after refactoring with state migration, which is its strongest aspect. However, it is significantly over-verbose, including unnecessary sections (capability statement, input parameters table for a non-existent API, revision history, prerequisite lists) and inlining content that should be in separate files or omitted entirely. The workflow is reasonably clear but lacks tight validation checkpoints between phases.
Suggestions
Remove the Overview, Capability Statement, Prerequisites, Input Parameters, and Revision History sections—these add no actionable value and consume significant tokens. Start directly with the analysis checklist and code examples.
Move the module documentation template and testing section into separate referenced files (e.g., MODULE_DOCS_TEMPLATE.md) rather than inlining them, since the testing section largely duplicates the terraform-test skill.
Add an explicit validation checkpoint between code transformation (step 3) and state migration (step 4), such as 'Run terraform validate and terraform plan before proceeding to state migration' with a clear feedback loop.
Trim the Analysis Phase from vague bullet lists to a concise, actionable checklist or a concrete example of analyzing a real configuration.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~350+ lines. It explains concepts Claude already knows (what modules are, what encapsulation means, what testing is), includes a full module documentation template, a revision history table, capability statements, and prerequisite lists that add no actionable value. The input parameters table describes a hypothetical API that doesn't exist. Much content could be cut by 60%+ without losing actionable guidance. | 1 / 3 |
Actionability | The skill provides fully executable HCL code for before/after refactoring, concrete state migration commands (both moved blocks and CLI), real validation examples, and copy-paste ready module structures. The code examples are complete and realistic. | 3 / 3 |
Workflow Clarity | The six phases are clearly sequenced 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 feedback loop for the overall refactoring process—e.g., no checkpoint after code transformation to validate before proceeding to state migration. For destructive state operations, the validation guidance is present but could be more prominent and structured. | 2 / 3 |
Progressive Disclosure | The skill references external skills (terraform-test, terraform-style-guide) and external docs, which is good. However, the bulk of content is monolithic—the full before/after code example, module documentation template, testing section, and refactoring patterns are all inline when they could be split into referenced files. The testing section essentially duplicates another skill's content inline rather than just pointing to it. | 2 / 3 |
Total | 8 / 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 | |
- Repository
- hashicorp/agent-skills
- Commit
b129bb5
- Reviewed
Table of Contents
Is this your skill?
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.