Terragrunt Skill for Claude Code
A Claude Code skill providing best practices guidance for Terragrunt infrastructure-as-code with OpenTofu/Terraform.
Architecture
Important: Catalog and Live repositories should be separate Git repositories. The live repo consumes units and stacks from the catalog via Git URLs.
Option A: Modules in Separate Repos
┌─────────────────────────────────────────────────────────────────────┐
│ SEPARATE REPOSITORIES │
├─────────────────────────┬─────────────────────────┬─────────────────┤
│ Module Repos │ Catalog Repo │ Live Repo │
│ (terraform-aws-*) │ (infrastructure- │ (infrastructure-
│ │ <org>-catalog) │ <org>-live) │
├─────────────────────────┼─────────────────────────┼─────────────────┤
│ • OpenTofu modules │ • units/ (wrappers) │ • root.hcl │
│ • Semantic versioning │ • stacks/ (templates) │ • account.hcl │
│ • Terratest │ • References modules │ • Deployments │
│ • Pre-commit hooks │ via Git URLs │ • Consumes │
│ │ │ catalog │
└─────────────────────────┴─────────────────────────┴─────────────────┘
▲ ▲ │
│ │ │
└─────────────────────────┴────────────────────────┘
Live repo references both via Git URLs
Option B: Modules in Catalog
┌───────────────────────────────────────────────────────────────┐
│ SEPARATE REPOSITORIES │
├─────────────────────────────────┬─────────────────────────────┤
│ Catalog Repo │ Live Repo │
│ (infrastructure-<org>-catalog)│ (infrastructure-<org>-live)
├─────────────────────────────────┼─────────────────────────────┤
│ • modules/ (OpenTofu modules) │ • root.hcl │
│ • units/ (module wrappers) │ • account.hcl │
│ • stacks/ (unit compositions) │ • Deployments │
│ • Discovered via `tg catalog` │ • Consumes catalog via Git │
│ • Single versioning strategy │ • `tg scaffold` for new │
└─────────────────────────────────┴─────────────────────────────┘
▲ │
└──────────────────────────────┘
Live repo references catalog
Trade-offs:
| Aspect | Option A (Separate Module Repos) | Option B (Modules in Catalog) |
|---|
| Versioning | Independent per module | Single catalog version |
| CI/CD | Dedicated pipeline per module | One pipeline for all |
| Complexity | More repos to manage | Simpler structure |
| Team ownership | Clear boundaries | Shared ownership |
terragrunt catalog | Discovers units/stacks | Discovers modules too |
Features
Catalog & Live Pattern
- Infrastructure Catalog: Reusable units and template stacks (separate repo)
- Infrastructure Live: Environment-specific deployments consuming the catalog
- Module Repos: Separate repositories with semantic versioning
Unit & Stack Patterns
- Values pattern for configuration injection
- Reference resolution (
"../unit" → dependency outputs)
- Unit interdependencies with mock outputs
- Conditional dependencies with
enabled and skip_outputs
CI/CD Pipelines
- GitLab CI with reusable templates
- GitHub Actions workflows
- AWS OIDC authentication (
assume-role-with-web-identity)
- GCP Workload Identity Federation
- SSH-based Git access (recommended over HTTPS)
Performance Optimization
- Provider caching (
--provider-cache)
- Two-layer caching architecture (local + network mirror)
- Benchmarking tools (Hyperfine, boring-registry)
- Explicit stacks for 2x faster runs
Multi-Account Deployments
- Cross-account role assumption
- Environment-based state bucket separation
- Hierarchical configuration (root.hcl → account.hcl → region.hcl → env.hcl)
Installation
This skill is distributed via Claude Code marketplace using .claude-plugin/marketplace.json.
Claude Code (Recommended)
/plugin marketplace add jfr992/terragrunt-skill
/plugin install terragrunt-skill@jfr992
Manual Installation
# Clone to Claude skills directory
git clone https://github.com/jfr992/terragrunt-skill.git ~/.claude/skills/terragrunt-skill
Verify Installation
After installation, try:
"Create a Terragrunt stack for a serverless API with Lambda, DynamoDB, and S3"
Claude will automatically use the skill when working with Terragrunt code.
Quick Start
1. Create a Catalog Repository
# Ask Claude to scaffold a new catalog
"Create a new infrastructure catalog with units for S3, DynamoDB, and Lambda"