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 primary action, but it lacks a 'Use when...' clause which is critical for skill selection. It would benefit from listing more specific concrete actions and including natural trigger terms that users would actually say when needing this skill.
Suggestions
Add an explicit 'Use when...' clause with trigger terms like 'refactor Terraform', 'split Terraform into modules', 'modularize infrastructure code', 'terraform module structure'.
List more specific concrete actions such as 'extract resources into child modules, define input/output variables, set up module composition, refactor terraform state'.
Include common user-facing keyword variations like 'tf modules', '.tf files', 'terraform refactoring', 'DRY terraform', 'reusable infrastructure code'.
| 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 'extract resources into child modules, define input/output variables, create module registries, refactor state files'. | 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, a missing 'Use when...' clause caps completeness at 2, and the 'what' is also only moderately detailed, placing this at 1. | 1 / 3 |
Trigger Term Quality | Includes relevant keywords like 'Terraform', 'modules', 'configurations', and 'HashiCorp', but misses common user variations such as 'refactor', 'tf modules', '.tf files', 'module structure', 'terraform refactoring', or 'split terraform code'. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on Terraform module refactoring is fairly specific and wouldn't conflict with most skills, but it could overlap with general Terraform skills or infrastructure-as-code skills since it doesn't clearly delineate its niche 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 Terraform refactoring guidance with realistic, executable code examples covering the full lifecycle from analysis to state migration. However, it is significantly over-verbose, explaining concepts Claude already understands and inlining content that should be in separate reference files. The workflow is reasonably clear but could better integrate validation checkpoints into the main sequence rather than scattering them across sections.
Suggestions
Cut the Overview, Capability Statement, Prerequisites, and Input Parameters sections—these explain things Claude already knows or are meta-information that doesn't help execution. Start directly with the workflow steps.
Remove the testing glossary definitions (Test Block, Run Block, Assert Block, Mock Provider, Test Modes) and simply reference the terraform-test skill with a brief note on what to test.
Move the full before/after code example, module documentation template, and refactoring patterns into separate referenced files (e.g., EXAMPLES.md, PATTERNS.md) to reduce the main skill to an actionable overview.
Integrate the state migration validation step (terraform plan to verify no changes) directly into Step 4 as an explicit checkpoint rather than relegating it to Common Pitfalls.
| 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, prerequisite lists, and input parameter tables that add little actionable value. The 'Capability Statement' and 'Overview' sections are redundant. The testing section copies definitions (what a 'Run Block' is, what an 'Assert Block' is) that Claude already knows. | 1 / 3 |
Actionability | The skill provides fully executable, copy-paste ready HCL code for before/after refactoring, state migration (both moved blocks and CLI commands), module interface design with validations, and concrete composition patterns. The code examples are complete and realistic. | 3 / 3 |
Workflow Clarity | The 6-step process is 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, the analysis phase is vague markdown bullets rather than concrete steps, and there's no explicit validation checkpoint between code transformation and state migration. The feedback loop for state migration errors is present but buried in 'Common Pitfalls' rather than integrated into the main workflow. | 2 / 3 |
Progressive Disclosure | The skill references external skills (terraform-test, terraform-style-guide, azure-verified-modules) and external documentation, which is good. However, the massive inline content—full before/after code examples, complete module documentation template, testing file structure, refactoring patterns, common pitfalls—should be split into separate reference files. The skill is monolithic despite having natural breakpoints for separate documents. | 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
de4323a
- 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.