terraform-test Skill Review: HashiCorp's Test-Writing Skill, Checked Against the Docs

The terraform-test skill is 11,148 bytes of markdown, stamped version: "0.0.2" in its own frontmatter. On August 4, 2026 an outside user filed an issue listing four problems in it. Eighty-four days later that issue has zero comments and is still open. The file was edited six days after the report, and the lines the report complains about are still in it.

Most of the skill is sensible. But it's HashiCorp's own skill for writing .tftest.hcl files, so I checked it against HashiCorp's documentation and found one more contradiction nobody has filed. I ran neither the skill nor Terraform. Everything below comes from the source files, GitHub, and published docs.

What the skill actually says

It's a reference sheet for Terraform's test framework: concepts, layout, run block anatomy, about a dozen patterns, cleanup order, CLI flags, eleven best practices and a troubleshooting table. Mocking, CI/CD and a full example live in three reference files, and the skill says when to open them:

That's good structure: the 11 KB body loads on trigger, the other 13 KB waits. Best practice 3 reads:

It also proposes a naming split (*_unit_test.tftest.hcl for plan mode, *_integration_test.tftest.hcl for apply) and version-gates mocking: "Terraform 1.7.0+ only — skip if the user's version is below 1.7". Small, but it keeps an agent from writing syntax your CLI rejects.

Security gate: I read all four files. No scripts, no network calls, no credential access, no instructions to read config or logs. The code blocks are HCL, two CI pipelines in YAML and a few shell lines.

What it costs you in context

These figures are arithmetic from file size (bytes ÷ 4), not a measured session cost. We didn't run the skill.

The frontmatter description is 340 characters, roughly 85 estimated tokens, and that's what sits in your skill list whether you use the skill or not. For scale: counting SKILL.md files only, this is the 13th smallest of the repo's 20, and all 20 together are 187,418 bytes, about 46,855 estimated tokens.

What the community reports

Public discussion is thin. I found no Hacker News threads about the repo, and the only GitHub activity touching this skill is one outside issue. Everything below is from GitHub unless noted.

Issue #93's reporter says the findings came from an automated review, and #56 shows an automated audit of this same repo getting a finding wrong. So I checked #93 claim by claim.

Checking the report against the source and the docs

• Plan-time ID assertion: the run-block example in SKILL.md still asserts aws_instance.example.id != "" under command = plan. A provider-assigned ID is normally unknown at plan time, so I think the reporter is right. I couldn't run it.
• Variable precedence comment: the weakest point. HashiCorp's docs say test-file variables beat environment variables, variable files and CLI input, and run-block values override file-level ones. The skill's comment is loose rather than flatly wrong, since the same file shows run-level overrides.
• -filter comment: SKILL.md says -filter=test_vpc_configuration selects "by run block name". The CLI docs describe -filter=testfile as limiting the run "to the specified test files". I agree with the reporter. CI_CD.md also builds its unit/integration split on -filter=unit_test, and I couldn't check whether a bare substring works.
• Undefined cross-run output: I can't confirm this one. The example module isn't shown, and run references read the module's outputs, so the claim may be wrong. Unverified either way.

Then there's the one nobody filed. MOCK_PROVIDERS.md says "Plan mode only — mocks don't work with command = apply", and repeats it in a code comment. HashiCorp's mocking page says: "From the perspective of a plan or apply operation executed in a Terraform test file, the mocked provider is creating actual resources with values that match the configuration." That's a direct contradiction of a stated limitation.

The same page says Terraform "generates data during the apply operation and returns (known after apply) values during the plan operation" unless you set override_during. The skill's mock examples assert fixed values such as aws_instance.example.id == "i-1234567890abcdef0" under command = plan, and the string override_during appears zero times in the repo's plugins directory. The docs don't say whether explicit defaults follow the same timing, so those plan-mode assertions are unverified.

How to install it

From the repo README, read this run. It shows the per-skill path form for other skills, and SKILLS.md lists this one at plugins/terraform/skills/terraform-test. I didn't run the installer.

# One skill
npx skills add hashicorp/agent-skills/plugins/terraform/skills/terraform-test

# Every skill in the repo
npx skills add hashicorp/agent-skills

# Claude Code bundle (16 Terraform skills)
claude plugin marketplace add hashicorp/agent-skills
claude plugin install terraform@hashicorp

The license is MPL-2.0, a file-level copyleft. That matters if you vendor and modify the files, as the #93 reporter did.

Where it earns its keep, and where it doesn't

It's worth having if you write Terraform modules and want an agent to draft .tftest.hcl files with a sane layout: the unit/integration split, expect_failures for validation rules, the 1.7 and 1.9 version notes. About 2,800 estimated tokens for the main file is a fair price.

Now the criticism. Some of what it generates may fail on first run. The default-to-plan advice sits next to examples that assert computed IDs, and the mock reference states something HashiCorp's docs contradict. Those aren't style quibbles: they can yield failing tests, or steer an agent away from apply-mode mocking for no reason. The CI example also passes long-lived AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY secrets to a job that creates real resources; an agent copying it will do the same, where OIDC role assumption is the usual alternative.

The maintenance signal is mixed. Three commits touch the file since January 2026, the latest on August 10. Meanwhile terraform-policy got merged updates (#97, #101), and PRs #103 and #104 are open. If you already know the test framework, read HashiCorp's docs and skip the skill. If you don't, use it, then run what it writes before trusting it.

FAQ

What does the terraform-test skill do?

It teaches an agent to write and run Terraform test files (.tftest.hcl): run blocks, assertions, mock providers and CI pipelines. SKILL.md is 11,148 bytes; the full set is 24,207 bytes, no scripts.

How much context does the terraform-test skill use?

By file-size arithmetic (bytes ÷ 4, an estimate, not a measured session cost), SKILL.md is about 2,787 tokens and all four files about 6,052. The reference files load only on request.

How do I install the terraform-test skill?

Run npx skills add hashicorp/agent-skills/plugins/terraform/skills/terraform-test. For the Claude Code bundle of 16 Terraform skills, run claude plugin marketplace add hashicorp/agent-skills, then claude plugin install terraform@hashicorp.

Does the terraform-test skill have known problems?

Yes. Issue #93 reported four problems on August 4, 2026 and was still open, with no comments, 84 days later. The mock reference also says mocks work in plan mode only, which conflicts with HashiCorp's mocking docs.

Skill by HashiCorp (SKILL.md frontmatter: Copyright IBM Corp. 2026), MPL-2.0. Source: github.com/hashicorp/agent-skills, reviewed at commit f706481 (2026-09-28). Quoted lines are short excerpts for review purposes. Review date October 27, 2026. Token figures are estimates (bytes ÷ 4); we did not run the skill. GitHub numbers and community reception shift over time.