The #1 Terraform skill for Claude Code and Codex, measured by GitHub stars.
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.
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.
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 • Philosophy
macOS / Linux:
git clone https://github.com/LukasNiessen/terrashark.git ~/.claude/skills/terrasharkWindows (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.
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.
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 .terrasharkThen 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.Done. Now ask Claude Code / Codex 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 scanningOr 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
terrashark-live-demo.mp4
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 | ||
| SKILL.md Activation Cost | ✅ ~600 tokens | ||
| Reference Granularity | ✅ 19 focused files | ❌ No focused reference library | |
| Token Burn Per Query | ✅ Low (load 1-2 small refs) | ||
| Diagnoses Before Generating | ✅ Step 2 requires diagnosis | ❌ No | ❌ No |
| Hallucination Prevention | ✅ Core design goal | ||
| Output Contract | ✅ Assumptions, tradeoffs, rollback | ❌ No | ❌ No |
| Failure-Mode Coverage | ✅ Identity, secrets, blast radius, CI, compliance | ||
| Migration Playbooks | ✅ 5 dedicated playbooks | ||
| Good/Bad/Neutral Examples | ✅ 3 dedicated files | ||
| Do/Don't Checklist | ✅ Dedicated file | ||
| Compliance Framework Mapping | ✅ ISO 27001, SOC 2, FedRAMP, GDPR, PCI DSS, HIPAA | ❌ No | |
| Trusted Module Awareness | ✅ AWS, Azure, GCP, OCI, IBM loaded conditionally | ❌ No | |
| MCP Integration Guidance | ✅ Dedicated reference | ❌ No | |
| Claude + Codex Support | ✅ First-class Claude Code and Codex setup | ||
| Security-First Defaults | ✅ Built into the workflow | ||
| CI/CD Templates | ✅ GitHub Actions, GitLab CI, Atlantis, Infracost | ✅ GitHub Actions, GitLab CI | |
| License | ✅ MIT | ❌ Not highlighted in skill listing |
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.
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.
- Keep
SKILL.mdprocedural 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.
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.
- 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_eachdrift; the exact spots where LLMs slip - Enforces exact version pinning for production, so module upgrades don't silently change generated resource addresses
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.
| 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.
- A focused
SKILL.mdexecution 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
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 |
Do/Don't pattern checklist |
references/mcp-integration.md |
MCP integration guidance |
references/conditional/trusted-modules.md |
Canonical community/vendor modules per cloud (conditional) |
references/token-balance-rationale.md |
Why the skill stays lean and where depth is kept |
.github/workflows/validate.yml |
CI validation for skill structure and links |
.github/PULL_REQUEST_TEMPLATE.md |
PR quality and failure-mode checklist |
.claude-plugin/marketplace.json |
Plugin metadata |
The skill runs as a failure-mode workflow whenever Claude Code 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
- 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
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. 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.
We highly appreciate contributions. See CONTRIBUTING.md and use the PR template for failure-mode and validation details.
• LukasNiessen - Creator and main maintainer
• janMagnusHeimann - Main maintainer
• TristanKruse - Main maintainer
Found a bug? Want to discuss features?
- Submit an issue on GitHub
- Join GitHub Discussions
If TerraShark helps your project, please consider:
- Starring the repository
- Suggesting new features
- Contributing code or documentation
This project is under the MIT license.
Version: v2.3.0
Website: https://terraformskill.com/
GitHub Pages: https://lukasniessen.github.io/terrashark/
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.