terrashark
# Terraform Skill for Claude Code and Codex: TerraShark <div align="center" name="top"> <img align="center" src="assets/logo.png" width="180" height="180" alt="TerraShark Logo"> <!-- spacer --> <p></p> [](https://docs.claude.ai/docs/agent-skills) [](https://developers.openai.com/codex/skills/) [](https://opensource.org/licenses/MIT) [](https://github.com/LukasNiessen/terrashark) </div> 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](https://developer.hashicorp.com/terraform/cloud-docs/recommended-practices). When guidance conflicts, it prioritizes HashiCorp's recommendations. --- [Quick Start](#-quick-start) • [Why TerraShark?](#-library-comparison) • [Token Strategy](#-token-strategy) • [What's Included](#-whats-included) • [How It Works](#-how-it-works) • [Philosophy](PHILOSOPHY.md) --- ## ⚡ 2 min Quickstart ### Option 1: Clone **macOS / Linux:** ```bash git clone https://github.com/LukasNiessen/terrashark.git ~/.claude/skills/terrashark ``` **Windows (Powershell):** ```powershell git clone https://github.com/LukasNiessen/terrashark.git "$env:USERPROFILE\.claude\skills\terrashark" ``` **Windows (Command Prompt):** ```powershell 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`: ```bash # 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): ```markdown ## Terraform When working with Terraform or OpenTofu, follow the workflow in `.terrashark/SKILL.md`. Load references from `.terrashark/references/` as needed. ``` ### That's it! 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:** ```bash /terrashark Create a multi-region S3 module with replication ``` ```bash /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 | ❌ No | | **Claude + Codex Support** | ✅ First-class Claude Code and Codex setup | ⚠️ Broad multi-agent setup | ⚠️ Claude plugin oriented | | **Security-First Defaults** | ✅ Built into the workflow | ⚠️ Checklist-style | ⚠️ Style-guide based | | **CI/CD Templates** | ✅ GitHub Actions, GitLab CI, Atlantis, Infracost | ✅ GitHub Actions, GitLab CI | ⚠️ Pipeline rules only | | **License** | ✅ MIT | ⚠️ Apache 2.0 | ❌ 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. ### 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: 1. **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. 2. **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. 3. **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` | 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 | ## 🔎 How It Works The skill runs as a failure-mode workflow whenever Claude Code handles Terraform or OpenTofu tasks: 1. **Capture execution context** - Runtime/version, providers, backend, execution path, risk level 2. **Diagnose likely failure mode(s)** - Identity churn, secret exposure, blast radius, CI drift, compliance gate gaps 3. **Load only relevant references** - Pull targeted guidance for the failure mode(s) in scope 4. **Propose fix path with controls** - Include risk notes, approvals, tests, and rollback expectations 5. **Generate implementation artifacts** - HCL changes, migration blocks, CI/policy updates 6. **Validate before finalize** - Runtime-appropriate command sequence and risk-tier checks 7. **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**. 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](CONTRIBUTING.md) and use the PR template for failure-mode and validation details. ## 💟 Community ### Maintainers • **[LukasNiessen](https://github.com/LukasNiessen)** - Creator and main maintainer • **[janMagnusHeimann](https://github.com/janMagnusHeimann)** - Main maintainer • **[TristanKruse](https://github.com/TristanKruse)** - Main maintainer ### Contributors <a href="https://github.com/LukasNiessen/terrashark/graphs/contributors"> <img src="https://contrib.rocks/image?repo=LukasNiessen/terrashark&max=1000&contributors=10" /> </a> ### Questions Found a bug? Want to discuss features? - Submit an [issue on GitHub](https://github.com/LukasNiessen/terrashark/issues/new/choose) - Join [GitHub Discussions](https://github.com/LukasNiessen/terrashark/discussions) If TerraShark helps your project, please consider: - Starring the repository - Suggesting new features - Contributing code or documentation ### Star History [](https://www.star-history.com/#LukasNiessen/terrashark&Date) ## 📄 License This project is under the **MIT** license. --- <p align="center"> <a href="#top"><strong>Go Back to Top</strong></a> </p> --- ## Other **Version:** v2.3.0 **Website:** https://terraformskill.com/ **GitHub Pages:** [https://lukasniessen.github.io/terrashark/](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.