Terraform Skill for Claude Code, Codex, Antigravity, and Gemini CLI: TerraShark
The #1 Terraform skill for Claude Code and Codex, measured by GitHub stars.
Fixes Hallucinations.
LLMs hallucinate a lot when it comes to Terraform. This skill fixes it. It includes best practices for Terraform and OpenTofu - good, bad, and neutral examples so the AI avoids common mistakes. Using TerraShark, the AI keeps proven practices in mind, eliminates hallucinations, and defaults to modular, reusable, security-first design.
Very Token-Efficient.
Most Terraform skills dump huge text-of-walls onto the agent and burn expensive tokens - with no upside. LLMs don't need the entire Terraform docs again. TerraShark was aggressively de-duplicated and optimized for maximum quality per token.
Based on HashiCorp's Official Best Practices.
TerraShark is primarily based on HashiCorp official recommended practices. When guidance conflicts, it prioritizes HashiCorp's recommendations.
Quick Start • Why TerraShark? • Token Strategy • What's Included • How It Works • Sponsor • Philosophy
⚡ 2 min Quickstart
Option 1: Clone
macOS / Linux:
git clone https://github.com/LukasNiessen/terrashark.git ~/.claude/skills/terrashark
Windows (Powershell):
git clone https://github.com/LukasNiessen/terrashark.git "$env:USERPROFILE\.claude\skills\terrashark"
Windows (Command Prompt):
git clone https://github.com/LukasNiessen/terrashark.git "%USERPROFILE%\.claude\skills\terrashark"
That's it. Claude Code auto-discovers skills in ~/.claude/skills/ - no restart needed.
Option 2: Marketplace
Claude Code has a built-in plugin system with marketplace support. Instead of cloning manually, you can add TerraShark's marketplace and install directly from the CLI:
/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 in this repo to register TerraShark as an installable plugin.
Option 3: Codex
Codex has no global skill system - setup is per-project. Clone TerraShark into your repo and reference it from your AGENTS.md:
# Clone into your project root
git clone https://github.com/LukasNiessen/terrashark.git .terrashark
Then add to your AGENTS.md (or create one in the repo root):
## Terraform
When working with Terraform or OpenTofu, follow the workflow in `.terrashark/SKILL.md`.
Load references from `.terrashark/references/` as needed.
Option 4: Antigravity
macOS / Linux:
git clone https://github.com/LukasNiessen/terrashark.git ~/.gemini/antigravity/skills/terrashark
Windows (PowerShell):
git clone https://github.com/LukasNiessen/terrashark.git "$env:USERPROFILE\.gemini\antigravity\skills\terrashark"
Antigravity auto-discovers skills in the skills directory — no restart needed.
Option 5: Gemini CLI
Gemini CLI discovers skills in several standard locations.
Global Installation (All Workspaces):
git clone https://github.com/LukasNiessen/terrashark.git ~/.gemini/skills/terrashark
Local Installation (Current Workspace):
git clone https://github.com/LukasNiessen/terrashark.git .gemini/skills/terrashark
Gemini CLI auto-discovers skills in these directories. Run /skills list in the CLI to verify.
That's it!
Done. Now ask Claude Code / Codex / Antigravity / Gemini CLI any Terraform question. TerraShark responses follow the 7-step failure-mode workflow and include an output contract with assumptions, tradeoffs, and rollback notes.
Invoke explicitly:
/terrashark Create a multi-region S3 module with replication
/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
Or just ask naturally - TerraShark activates automatically for any Terraform/OpenTofu task:
Review my main.tf for security issues
Migrate this module from count to for_each
🎬 Demo
https://github.com/user-attachments/assets/2bc4c9ff-9f54-4a49-8bf0-5cfc0f26dec6
📊 Library Comparison
Here's how TerraShark compares to other Terraform and OpenTofu agent skills:
| Feature | TerraShark | Anton Babenko terraform-skill | terraform-patterns |
|---|
| Core Architecture | ✅ Failure-mode workflow | ⚠️ Static reference manual | ⚠️ Pattern checklist |
| SKILL.md Activation Cost | ✅ ~600 tokens | ⚠️ ~4,400 tokens | ⚠️ Single broad reference |
| Reference Granularity | ✅ 19 focused files | ⚠️ 6 large files | ❌ No focused reference library |
| Token Burn Per Query | ✅ Low (load 1-2 small refs) | ⚠️ High for deep references | ⚠️ Loads broad guidance |
| Diagnoses Before Generating | ✅ Step 2 requires diagnosis | ❌ No | ❌ No |
| Hallucination Prevention | ✅ Core design goal | ⚠️ Indirect via best practices | ⚠️ Indirect via patterns |
| Output Contract | ✅ Assumptions, tradeoffs, rollback | ❌ No | ❌ No |
| Failure-Mode Coverage | ✅ Identity, secrets, blast radius, CI, compliance | ⚠️ General state/security advice | ⚠️ General anti-pattern summary |
| Migration Playbooks | ✅ 5 dedicated playbooks | ⚠️ Partial inline snippets | ⚠️ Import and moved-block notes |
| Good/Bad/Neutral Examples | ✅ 3 dedicated files | ⚠️ Inline DO/DON'T examples | ⚠️ Inline BAD/GOOD snippets |
| Do/Don't Checklist | ✅ Dedicated file | ⚠️ Inline only | ⚠️ Inline only |
| Compliance Framework Mapping | ✅ ISO 27001, SOC 2, FedRAMP, GDPR, PCI DSS, HIPAA | ⚠️ Scanner-oriented guidance | ❌ No |
| Trusted Module Awareness | ✅ AWS, Azure, GCP, OCI, IBM loaded conditionally | ⚠️ AWS module context | ❌ No |
| MCP Integration Guidance | ✅ Dedicated reference | ⚠️ Optional Terraform MCP mention |
As you see in the table, there are some features that are only supported by us. Here is a brief highlight of those that we believe are the most critical of them:
-
Failure-mode workflow: TerraShark does not just give the agent Terraform facts. It forces the agent to identify the likely failure mode first, then load the exact reference material needed for that risk.
-
Output contract: TerraShark responses include assumptions, remediation choices, tradeoffs, validation steps, and rollback notes. Other skills leave that structure to the model.
-
Token efficiency: TerraShark keeps the activation path tiny and moves depth into focused references. This gives the agent the right Terraform context without turning every request into a large reference dump.
-
Compliance mapping: TerraShark includes explicit mappings for ISO 27001, SOC 2, FedRAMP, GDPR, PCI DSS, and HIPAA. Other skills focus more on scanners than audit-ready control mapping.
-
Trusted module awareness: TerraShark knows when to prefer mature vendor and community modules for AWS, Azure, GCP, Oracle Cloud, and IBM Cloud, reducing the surface area for hallucinated raw resources.
-
LLM-specific hallucination prevention: TerraShark is designed around the ways AI agents fail at infrastructure code: unstable identity, leaked secrets, wide blast radius, CI drift, and weak compliance gates.
TerraShark vs terraform-skill
The key difference is architectural. terraform-skill is a static reference manual: it dumps ~4,400 tokens into context on every activation, then loads additional reference files that can be over 1,000 lines each. It gives Claude information but never tells it how to think about a problem. There's no diagnosis step, no risk assessment, and no structured output - Claude reads the reference and generates whatever it thinks fits.
TerraShark takes the opposite approach. The core SKILL.md is an 86-line operational workflow that costs ~600 tokens on activation - over 7x leaner. Instead of front-loading a wall of text, it forces Claude through a diagnostic sequence: capture context → identify failure modes → load only the relevant references → propose fixes with explicit risk controls → validate → deliver a structured output contract.
This matters for three reasons:
-
Token efficiency. terraform-skill burns ~4,400 tokens just to activate, before any reference files. A single reference file like module-patterns.md (1,126 lines, ~7,000 tokens) can double the cost again. TerraShark's activation is ~600 tokens, and its 19 granular reference files mean Claude loads only what's needed - typically one or two small, focused docs instead of one massive dump.
-
Hallucination prevention. terraform-skill provides good patterns but never asks Claude to diagnose what could go wrong. TerraShark's Step 2 forces failure-mode identification before any code is generated. Step 4 requires explicit risk controls for every fix. Step 7 enforces an output contract with assumptions, tradeoffs, and rollback notes. This is the difference between giving someone a cookbook and giving them a diagnostic checklist.
-
Reference coverage. TerraShark ships 19 focused reference files covering failure modes, backend-specific state safety, migration playbooks, good/bad/neutral examples, do/don't checklists, compliance framework mappings, and MCP integration. terraform-skill has 6 larger files that go deep on testing and module patterns but lack migration playbooks, explicit anti-pattern banks, compliance mappings beyond a few frameworks, and MCP guidance.
In short: TerraShark is the better skill due to 7x leaner activation, failure-mode-first diagnostic workflow, output contracts, granular references, and LLM-specific hallucination prevention. terraform-skill wins on HCL example depth and testing docs, but TerraShark's architecture is fundamentally better designed for the core use case of LLM-assisted IaC generation.
🕵️ Token Strategy
- Keep
SKILL.md procedural and compact
- Keep references focused on failure-prone decisions
- Exclude broad tutorial material with low safety impact
- Add depth only when measured quality would otherwise drop
See references/token-balance-rationale.md for the full decision and tradeoffs.
🧱 Trusted Module Awareness
Hand-rolled resource blocks are one of the largest hallucination surfaces for LLMs; attribute names, defaults, and iteration shapes are where models drift. TerraShark recognizes the major vendor-maintained and community module registries and defaults to using them instead of generating raw resources, whenever a mature module covers the requested service.
How it helps
- A pinned registry module replaces hundreds of lines of hand-rolled HCL with a version-locked interface already tested across many production stacks
- Removes attribute-name, default-value, and
for_each drift; the exact spots where LLMs slip
- Enforces exact version pinning for production, so module upgrades don't silently change generated resource addresses
When it loads (lean-token approach)
references/conditional/trusted-modules.md is pulled into context only when the detected provider is one of the supported clouds. AWS-only projects never pay the token cost for Azure or GCP guidance, and vice versa, matching TerraShark's core token-efficiency design.
Supported providers
| Cloud | Registry namespace | Program |
|---|
| AWS | terraform-aws-modules | Community standard |
| Azure | Azure | Azure Verified Modules (AVM) |
| GCP | terraform-google-modules | Cloud Foundation Toolkit |
| Oracle Cloud | oracle-terraform-modules | Vendor-maintained |
| IBM Cloud | terraform-ibm-modules | IBM Deployable Architectures |
Other ecosystems (Alibaba Cloud, DigitalOcean, Hetzner, etc.) are intentionally not included yet, their module programs are still small or early-stage, so recommending them as defaults would trade one failure mode (hallucinated attributes) for another (unmaintained wrappers). If a provider's ecosystem matures, it can be added later.
🐣 What's Included
- A focused
SKILL.md execution flow
- Failure-mode-first guidance to prevent common IaC hallucinations
- Core failure-mode references: identity churn, secret exposure, blast radius, CI drift, compliance gates
- Backend-specific state safety loaded conditionally for state storage, locking, migration, and restore work
- Expanded architecture guidance (state, boundaries, module roles)
- Refactor/migration playbooks for safe evolution
- Stronger CI/CD and governance patterns (including Atlantis + Infracost)
- Risk-based test depth guidance with native test caveats and Terratest coverage
- Rewritten good/bad/neutral example bank
- Do/Don't pattern bank and MCP integration guidance
- Trusted community/vendor module awareness (AWS, Azure, GCP, OCI, IBM) loaded conditionally
🔲 Repository Layout
Here an overview of the repository layout.
| File | Description |
|---|
SKILL.md | Operational workflow for TerraShark |
PHILOSOPHY.md | Design strategy, architecture decisions, token experiment |
references/identity-churn.md | Address stability, count/for_each, moved safety |
references/secret-exposure.md | Preventing secret leakage through state/logs/artifacts |
references/blast-radius.md | State boundaries, environment isolation, apply impact control |
references/ci-drift.md | Production CI drift prevention and plan/apply integrity |
references/compliance-gates.md | Policy gates, approvals, evidence, framework mappings |
references/structure-and-state.md | State, boundaries, and apply safety |
references/conditional/backend-state-safety.md | Backend-specific state safety and migration guardrails |
references/module-architecture.md | Module role model and composition rules |
references/coding-standards.md | Naming, typing, iteration, versioning |
references/migration-playbooks.md | moved/import/refactor/upgrade playbooks |
references/testing-matrix.md | Test tiering, native test caveats, Terratest guidance |
references/ci-delivery-patterns.md | CI stages and production-oriented pipeline templates |
references/security-and-governance.md | Security controls and operational governance |
references/quick-ops.md | Command sequence and troubleshooting shortcuts |
references/examples-good.md | Strong implementation examples |
references/examples-bad.md | Anti-pattern examples |
references/examples-neutral.md | Context-based tradeoff examples |
references/do-dont-patterns.md |
🔎 How It Works
The skill runs as a failure-mode workflow whenever Claude Code, Codex, Antigravity, or Gemini CLI handles Terraform or OpenTofu tasks:
- Capture execution context - Runtime/version, providers, backend, execution path, risk level
- Diagnose likely failure mode(s) - Identity churn, secret exposure, blast radius, CI drift, compliance gate gaps
- Load only relevant references - Pull targeted guidance for the failure mode(s) in scope
- Propose fix path with controls - Include risk notes, approvals, tests, and rollback expectations
- Generate implementation artifacts - HCL changes, migration blocks, CI/policy updates
- Validate before finalize - Runtime-appropriate command sequence and risk-tier checks
- Deliver complete output - Assumptions, remediation choices, tradeoffs, validation plan, recovery notes
🐲 Scope
- Terraform and OpenTofu module design/review/refactoring
- Safe migration workflows for existing stacks
- CI/CD and policy integration for infrastructure delivery
- Blast-radius reduction and operational safety
ℹ️ FAQ
Q: Does this work with OpenTofu?
Yes. TerraShark supports both Terraform and OpenTofu. The workflow captures runtime/version first and adapts guidance accordingly.
Q: Will this slow down my AI interactions?
No. The skill is designed for low token overhead. Only relevant references should be loaded for a given failure mode.
Q: Can I use this outside Claude Code?
Yes. The references are plain Markdown and can be used from any workflow or AI assistant, including Codex, Antigravity, and Gemini CLI. The trigger behavior in SKILL.md is optimized for skill-enabled environments.
Q: How was the content validated?
We started with much larger references and a large automated test suite, then repeatedly removed sections and re-tested. If quality dropped, content was restored. If quality stayed stable, content remained out.
🦊 Contributing
We highly appreciate contributions. See CONTRIBUTING.md and use the PR template for failure-mode and validation details.
💟 Community
Maintainers
• LukasNiessen - Creator and main maintainer
• janMagnusHeimann - Main maintainer
• TristanKruse - Main maintainer
Contributors
Questions
Found a bug? Want to discuss features?
If TerraShark helps your project, please consider:
- Starring the repository
- Suggesting new features
- Contributing code or documentation
Star History
📄 License
This project is under the MIT license.
Other
Version: v2.3.0
Website: https://terraformskill.com/
GitHub Pages: https://lukasniessen.github.io/terrashark/
Conditional Reference Retrieval (CRR)
TerraShark adheres to Conditional Reference Retrieval (CRR): conditional references live under references/conditional/, are loaded only when concrete signals are detected, and neighboring conditional references are not loaded unless the task spans multiple detected routes.
@lukasniessen