CtrlK
BlogDocsLog inGet started
Tessl Logo

refactor-module

Transform monolithic Terraform configurations into reusable, maintainable modules following HashiCorp's module design principles and community best practices.

80

1.05x
Quality

37%

Does it follow best practices?

Impact

84%

1.05x

Average score across 10 eval scenarios

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./terraform/module-generation/skills/refactor-module/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

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'.

DimensionReasoningScore

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').

DimensionReasoningScore

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.

Validation10 / 11 Passed

Validation for skill structure

CriteriaDescriptionResult

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
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.