TerraShark: A Terraform Skill for Claude Code, Codex, and Gemini CLI

What TerraShark Solves: LLM Terraform Hallucinations

LLMs frequently produce Terraform configurations with invented argument names, deprecated resource blocks, or missing required fields. The problem is specific to Terraform: the provider ecosystem is large and changes frequently, and the gap between what a model learned during training and what the current provider documentation says can produce code that parses but fails on apply.

TerraShark addresses this by giving the agent a structured workflow before it writes any code. The skill file opens with diagnosis: the agent must identify failure modes, blast radius, and compliance concerns before generating configuration. It then produces an output contract listing assumptions, trade-offs, and rollback notes alongside the code. This sequence is designed to catch errors at the reasoning stage rather than at plan or apply time.

The README acknowledges the specific issue directly: LLMs hallucinate with Terraform, and TerraShark's core design goal is to fix that. Whether it eliminates hallucinations depends on the model and the complexity of the task, but the structured workflow makes the agent's reasoning visible rather than implicit.

The 7-Step Failure-Mode Workflow and Output Contract

TerraShark's SKILL.md defines a 7-step workflow that every Terraform task passes through. The README does not enumerate each step sequentially by number, but describes the pattern: the agent diagnoses the problem, considers failure modes, writes the configuration, and produces a contract with assumptions, trade-offs, and rollback notes.

Five dedicated migration playbooks cover specific transitions: from count to for_each, from monolithic to modular layouts, state file splits, moved blocks to prevent resource recreation, and pipeline integration with plan-on-PR and gated-apply-on-merge workflows. The README gives an example invocation that illustrates the complexity TerraShark handles:

/terrashark Refactor our EKS stack into separate state files per environment, add moved blocks to avoid recreation, set up a GitHub Actions pipeline with plan on PR and gated apply on merge, and wire in Checkov for compliance scanning

The output contract requirement is a concrete difference from similar skill files. The agent must document what it assumed, what the trade-offs are, and how to roll back, in addition to producing the configuration. For simpler tasks, invocation is straightforward:

/terrashark Create a multi-region S3 module with replication

Installing TerraShark in Claude Code

Claude Code discovers skills in `~/.claude/skills/` automatically without a restart. The standard installation clones the repository there:

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

For Windows via PowerShell:

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

Alternatively, Claude Code has a built-in plugin marketplace. Add TerraShark's marketplace and install directly:

/plugin marketplace add LukasNiessen/terrashark
/plugin install terrashark

Or use the interactive plugin manager: run `/plugin`, switch to the Discover tab, and install from there. The marketplace reads the `.claude-plugin/marketplace.json` file in the TerraShark repository to register the plugin.

After installation, TerraShark activates automatically when Claude Code detects a Terraform or OpenTofu task. To invoke it explicitly, prefix the request with `/terrashark`.

Installing TerraShark for Codex, Antigravity, and Gemini CLI

Codex has no global skill system, so installation is per-project. Clone TerraShark into the project root:

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

Then add a reference to the `AGENTS.md` file at the repository root, creating it if it does not exist:

## Terraform

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

For Antigravity on macOS or Linux:

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

For Gemini CLI, the global installation path is `~/.gemini/skills/terrashark`. Both Antigravity and Gemini CLI auto-discover skills in their respective directories without requiring a restart. Running `/skills list` in the Gemini CLI verifies the installation.

Token Efficiency and the 19-File Reference Architecture

The README includes a comparison of TerraShark against two other Terraform skill packages: Anton Babenko's terraform-skill and terraform-patterns. The comparison lists TerraShark's core SKILL.md activation cost at roughly 600 tokens, versus roughly 4,400 tokens for the Babenko skill. The difference comes from how references are structured.

TerraShark uses 19 focused reference files that the agent loads selectively based on the task. A query about security isolation loads one or two small files. A query about state management loads different ones. The Babenko skill uses 6 large files, so a deep query loads all of them at once. terraform-patterns has no focused reference library.

Three dedicated files cover good examples, bad examples, and neutral examples of Terraform patterns. The README explains this as intentional: agents learn to avoid mistakes by seeing explicit counterexamples, not just positive guidance. Five migration playbooks address the specific transitions that tend to produce broken state: count-to-for_each, monolithic-to-modular, state file separation, moved blocks, and CI pipeline setup.

The repository root contains `SKILL.md`, an `assets/` directory, a `docs/` directory, and a `references/` directory. The skill is language-agnostic in the sense that it contains no executable code, only Markdown reference files designed to be loaded into agent context.

Limitations: Scope Boundaries and What TerraShark Does Not Cover

TerraShark guides the agent's reasoning process and grounds it in documented best practices, but it does not replace access to current provider documentation. Terraform provider schemas change with each provider release. The reference files in TerraShark reflect HashiCorp's architectural recommendations, not live provider API schemas. An agent following the TerraShark workflow still needs to verify specific resource argument names and types against the provider's own documentation.

TerraShark is also scoped to Terraform and OpenTofu. It covers no other infrastructure-as-code tools. Teams using Pulumi, CDK, or Crossplane would need different skill files.

A comparable alternative is Anton Babenko's terraform-skill, which provides similar Terraform guidance as a larger skill file. The practical difference per the README is that TerraShark splits guidance into many focused files and requires an explicit diagnosis step before code generation, while the Babenko skill delivers guidance as fewer but larger reference documents without the failure-mode-first workflow. Teams that want the full documentation weight without per-query selective loading would find the Babenko approach simpler, at the cost of higher token consumption per interaction.

The repository has no published GitHub releases. Updates are tracked through the CHANGELOG.md file. The last push was on 2026-09-17.

Editorial conclusion

TerraShark is the right starting point for any team using Claude Code, Codex, Antigravity, or Gemini CLI to write or refactor Terraform or OpenTofu code and finding that the agent produces plausible-looking but non-functional configurations. Install it with a single git clone, invoke it explicitly for complex tasks, and verify that your agents handle the 7-step workflow before relying on its output contract for production infrastructure. The main limitation is scope: TerraShark guides the agent's approach, but the agent still needs API access to valid provider documentation, and changes in provider resource schemas can outpace the reference files.

Frequently asked questions

Official sources

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