# terrashark

Adopt this skill: https://proskills.md/skills/other/lukasniessen-terrashark

Page: https://proskills.md/skills/other/lukasniessen-terrashark
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 3371
upstream: https://github.com/lukasniessen/terrashark/blob/HEAD/SKILL.md

```text
---
name: terrashark
description: "Prevent Terraform/OpenTofu hallucinations by diagnosing and fixing failure modes: identity churn, secret exposure, blast-radius mistakes, CI drift, and compliance gate gaps. Use when generating, reviewing, refactoring, or migrating IaC and when building delivery/testing pipelines."
---

# Terrashark: Failure-Mode Workflow for Terraform/OpenTofu

Run this workflow top to bottom.

## 1) Capture execution context

Record before writing code:
- runtime (`terraform` or `tofu`) and exact version
- provider(s), target platform, and state backend
- execution path (local CLI, CI, HCP Terraform/TFE, Atlantis)
- environment criticality (dev/shared/prod)

If unknown, state assumptions explicitly.

## 2) Diagnose likely failure mode(s)

Select one or more based on user intent and risk:
- identity churn: resource addressing instability, refactor breakage
- secret exposure: secrets in state, logs, defaults, artifacts
- blast radius: oversized stacks, weak boundaries, unsafe applies
- CI drift: version mismatch, unreviewed applies, missing artifacts
- compliance gate gaps: missing policies/approvals/audit controls

## 3) Load only the relevant reference file(s)

Primary references:
- `references/identity-churn.md`
- `references/secret-exposure.md`
- `references/blast-radius.md`
- `references/ci-drift.md`
- `references/compliance-gates.md`

Supplemental references (only when needed):
- `references/testing-matrix.md`
- `references/quick-ops.md`
- `references/examples-good.md`
- `references/examples-bad.md`
- `references/examples-neutral.md`
- `references/coding-standards.md`
- `references/module-architecture.md`
- `references/ci-delivery-patterns.md`
- `references/security-and-governance.md`
- `references/do-dont-patterns.md`
- `references/mcp-integration.md`

Conditional references (CRR; load only on detected signals):
- `references/conditional/backend-state-safety.md` (backend is `s3`, `azurerm`, `gcs`, `remote`, `cloud`, `pg`, `consul`, or `local`, or task mentions backend migration, locking, state backup, or restore)
- `references/conditional/trusted-modules.md` (provider is `aws`, `azurerm`, `google`, `oci`, or `ibm`)

Do not load multiple conditional references unless the task spans multiple detected backends, providers, or tools.

## 4) Propose fix path with explicit risk controls

For each fix, include:
- why this addresses the failure mode
- what could still go wrong
- guardrails (tests, approvals, rollback)

## 5) Generate implementation artifacts

When applicable, output:
- HCL changes (typed vars, stable keys, bounded versions)
- migration blocks (`moved`, import strategy)
- CI pipeline updates (plan/apply separation, artifacts, policy checks)
- compliance controls (approvals, policy rules, evidence paths)

When a trusted registry module covers the requested resource and the user has not asked for raw HCL, default to that module with an exact `version` pin (see `references/conditional/trusted-modules.md`).

## 6) Validate before finalize

Always provide command sequence tailored to runtime and risk tier.
Never recommend direct production apply without reviewed plan and approval.

## 7) Output contract

Return:
- assumptions and version floor
- selected failure mode(s)
- chosen remediation and tradeoffs
- validation/test plan
- rollback/recovery notes for destructive-impact changes
```

## File: README.md
upstream: https://github.com/lukasniessen/terrashark/blob/HEAD/README.md

````text
# Terraform Skill for Claude Code, Codex, Antigravity, and Gemini CLI: TerraShark

<div align="center" name="top">
  <img align="center" src="assets/logo.png" width="180" height="180" alt="TerraShark Logo">

<!-- spacer -->
<p></p>

[![Claude Skill](https://img.shields.io/badge/Claude-Skill-6272F5)](https://docs.claude.ai/docs/agent-skills)
[![Codex Skill](https://img.shields.io/badge/Codex-Skill-10A37F)](https://developers.openai.com/codex/skills/)
[![Gemini Skill](https://img.shields.io/badge/Gemini-Skill-8E75C2)](https://geminicli.com/docs/cli/skills)
[![Antigravity Skill](https://img.shields.io/badge/Antigravity-Skill-blue)](https://antigravity.google/docs/skills)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub stars](https://img.shields.io/github/stars/LukasNiessen/terrashark.svg)](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) • [Sponsor](https://github.com/sponsors/LukasNiessen) • [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.
```

### Option 4: Antigravity

**macOS / Linux:**

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

**Windows (PowerShell):**

```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):**

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

**Local Installation (Current Workspace):**

```bash
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:**

```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 condi
````
