TerraShark: a Terraform skill for Claude Code, Codex, Antigravity and Gemini CLI

What TerraShark is solving, and for whom

Terraform is a bad fit for language models. Resource arguments are numerous, provider schemas change, and a plausible-looking attribute that does not exist fails only at plan time. The repository states the problem plainly: LLMs hallucinate a lot when it comes to Terraform, and TerraShark fixes it. The remedy is not a validator or a linter. It is a set of instructions the agent reads before it answers, containing good, bad and neutral examples so the model has something concrete to imitate or avoid.

The audience is narrow and specific. You need an agent that supports the skill format: Claude Code, Codex, Antigravity or Gemini CLI. You need to be writing Terraform or OpenTofu rather than another infrastructure tool. And you need the agent to be the thing producing your HCL, because nothing here runs in CI. A team that writes Terraform by hand and reviews it in a pull request gets no benefit from installing markdown into a skills directory.

The mechanism: a small SKILL.md plus 19 reference files

The repository layout is the clearest statement of the design. Alongside README.md, LICENSE, CHANGELOG.md and PHILOSOPHY.md, there are two directories that do the work: SKILL.md at the root and references/ beneath it. The comparison table in the README puts the activation cost of SKILL.md at roughly 600 tokens, against roughly 4,400 for the Anton Babenko terraform-skill, and describes references/ as 19 focused files where the alternative has 6 large ones.

The claim about token burn follows from that split. A skill that loads a single large manual pays the whole cost on every question. TerraShark's stated approach is to keep the always-loaded file small and let the agent pull one or two small references when the task calls for them. Whether that works in practice depends on the agent's retrieval behaviour, which the repository does not document, so treat the token figures as the author's measurements rather than something you can verify from the files.

The substantive part is the workflow. According to the README, responses follow a 7-step failure-mode workflow, and step 2 requires diagnosis before generation. That ordering is the real difference from a static reference manual: the agent is supposed to identify what is likely to go wrong before it writes anything. The README also mentions an output contract covering assumptions, tradeoffs and rollback notes. The README does not spell out all seven steps or the full contract, so the only way to see them is to read SKILL.md itself.

Installing TerraShark for Claude Code and running a first task

For Claude Code on macOS or Linux, the README gives a single clone into the skills directory. The README states that Claude Code auto-discovers skills in ~/.claude/skills/ and that no restart is needed.

git clone https://github.com/LukasNiessen/terrashark.git ~/.claude/skills/terrashark

Windows users get the equivalent path in PowerShell:

git clone https://github.com/LukasNiessen/terrashark.git "$env:USERPROFILE\.claude\skills\terrashark"

There is a second route that avoids cloning by hand. The README describes a plugin marketplace, backed by .claude-plugin/marketplace.json in the repository, installed from the Claude Code CLI:

/plugin marketplace add LukasNiessen/terrashark
/plugin install terrashark

Once it is in place, the README says TerraShark activates automatically for any Terraform or OpenTofu task, and that you can also invoke it explicitly with the /terrashark command. A first real use, taken from the README's own examples, is a module request:

/terrashark Create a multi-region S3 module with replication

What you should see is a response that follows the 7-step failure-mode workflow and carries the output contract: assumptions, tradeoffs and rollback notes. If the reply is ordinary Terraform prose with no stated assumptions, the skill did not load, and the first thing to check is whether the clone landed in the directory the agent actually scans.

Codex, Antigravity and Gemini CLI need different setup

Codex has no global skill system, and the README is direct about the consequence: setup is per-project. You clone the repository into the project root under a dot-directory and then reference it from AGENTS.md.

git clone https://github.com/LukasNiessen/terrashark.git .terrashark

The AGENTS.md entry the README shows points the agent at the workflow file and the reference directory:

## Terraform

When working with Terraform or OpenTofu, follow the workflow in `.terrashark/SKILL.md`.
Load references from `.terrashark/references/` as needed.

Antigravity and Gemini CLI both use a skills directory instead. Antigravity takes the same clone pattern into ~/.gemini/antigravity/skills/terrashark, with a PowerShell variant using the environment variable, and the README says it auto-discovers skills there without a restart. Gemini CLI is more flexible: it reads a global location at ~/.gemini/skills/terrashark or a workspace-local one at .gemini/skills/terrashark, and the README points at /skills list as the way to confirm the skill was picked up.

The practical difference is durability. A global Claude Code or Antigravity install follows you across repositories. The Codex path lives inside one repository, which means every teammate who wants it has to clone it and every new project starts over. The README does not describe a shared or organization-level installation for Codex.

Where TerraShark stops helping

The skill shapes what the model writes. It does not check what Terraform does. Nothing in the repository layout suggests a hook into terraform plan, a policy engine, or a CI step, and the README makes no such claim. So a hallucinated argument that survives into the HCL still fails at plan time exactly as it would without the skill. The difference is that the failure is less likely, not that it is caught.

The second boundary is the agent. TerraShark is markdown consumed by a skill system. If your assistant does not implement that format, there is no fallback path, no CLI, and no library to import. The four supported agents are the whole surface.

The third is scope. The README says the material is primarily based on HashiCorp official recommended practices and that conflicting guidance is resolved in HashiCorp's favour. That is a defensible default, but it means the skill carries an opinion about module structure, state layout and naming that may not match an existing codebase. A team with established conventions could find the agent arguing with its own repository. The README does not describe a way to override or extend the guidance.

TerraShark against the Anton Babenko terraform-skill

The README's own comparison table names two alternatives: the Anton Babenko terraform-skill and terraform-patterns. The distinction it draws is architectural. Anton Babenko's skill is described as a static reference manual with six large files and no diagnosis step. TerraShark is described as a failure-mode workflow with 19 focused files, where step 2 requires the agent to diagnose before it generates.

That is a real difference in how the two spend context. A static manual gives the model a body of correct practice and trusts it to apply the right part. A workflow tells the model what order to do things in. Neither approach validates output, and both depend on the agent actually reading the files. If your complaints about AI-written Terraform are about style and structure, a broad manual may serve you as well. If they are about the model confidently inventing resources, the diagnose-first ordering is the part worth evaluating, and the only way to evaluate it is to run the same prompt against both.

Maintenance, licence and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-13, two days before this article. There are no releases retrieved for the project, so there is no version number to pin and no changelog entry to read before upgrading. CHANGELOG.md exists at the root, which is where changes would be recorded.

That has a practical consequence for installation. Cloning puts a moving branch on your disk, and the Claude Code marketplace route installs from the same repository. Neither gives you a tag to hold. If you want a fixed revision, you have to pin the clone yourself, and the README does not describe how the marketplace handles updates.

The licence is MIT, stated in the README badge and present as a LICENSE file at the root. MIT permits commercial use and modification, and it requires that the copyright notice and permission notice be included in copies or substantial portions. TerraShark is distributed as text that an agent reads, so redistributing it inside an internal tool or a fork means carrying that notice. This is a description of what the licence says, not legal advice; if you plan to redistribute it, read LICENSE and decide with whoever handles that for you.

Editorial conclusion

Adopt TerraShark if your Terraform work already runs through Claude Code, Codex, Antigravity or Gemini CLI and you want the agent to state assumptions, tradeoffs and rollback notes before it writes HCL. Skip it if you do not use one of those agents, or if your review process is a human reading a pull request, because the skill only changes what the model produces, not what Terraform applies. Before trusting it on a live stack, clone it into a scratch directory, run /terrashark on a module you already know well, and check whether the 7-step workflow and the output contract actually appear in the reply.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. LukasNiessen/terrashark on GitHub
4. Project website
5. README