Terragrunt Agent Skill

An agent skill providing best practices guidance for Terragrunt (0.68 to 1.2) infrastructure-as-code with OpenTofu or Terraform. Version differences are covered in version-compatibility.md. It follows the open Agent Skills spec (https://agentskills.io/specification), so it works with any compatible agent (Claude Code, Codex, Cursor, Gemini CLI, …).

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

The skill lives in skills/terragrunt-skill/ (a standard Agent Skills directory: SKILL.md + references/ + assets/).

git clone https://github.com/jfr992/terragrunt-skill.git ~/src/terragrunt-skill
# Codex, Cursor, Gemini CLI (shared user dir)
mkdir -p ~/.agents/skills && ln -s ~/src/terragrunt-skill/skills/terragrunt-skill ~/.agents/skills/terragrunt-skill
# Codex (plugin marketplace: .agents/plugins/marketplace.json + root plugin.json)
codex plugin marketplace add jfr992/terragrunt-skill   # optionally --ref <tag>
codex plugin add terragrunt-skill@jfr992
# Claude Code (marketplace)
/plugin marketplace add jfr992/terragrunt-skill
/plugin install terragrunt-skill@jfr992
# or Claude Code manual
mkdir -p ~/.claude/skills && ln -s ~/src/terragrunt-skill/skills/terragrunt-skill ~/.claude/skills/terragrunt-skill
# Per-repo (team): commit or symlink into <repo>/.agents/skills/terragrunt-skill

Agent	Skill directories read
Codex	`.agents/skills`, `~/.agents/skills` (or the plugin marketplace via `.agents/plugins/marketplace.json`)
Cursor	`.agents/skills`, `~/.agents/skills`, also `.cursor/skills`, `.claude/skills`
Gemini CLI	`.agents/skills`, `~/.agents/skills`, also `.gemini/skills`
Claude Code	`.claude/skills`, `~/.claude/skills` only (or the plugin marketplace via `.claude-plugin/marketplace.json`)
GitHub Copilot, Goose, Amp	`.agents/skills` — reported, unverified

Windows: symlinks may need admin/developer mode — copy the skills/terragrunt-skill directory instead of ln -s.

Verify Installation

After installation, try:

"Create a Terragrunt stack for a serverless API with Lambda, DynamoDB, and S3"

Your agent will automatically use the skill when working with Terragrunt code.

Quick Start

1. Create a Catalog Repository

# Ask your agent to scaffold a new catalog
"Create a new infrastructure catalog with units for S3, DynamoDB, and Lambda"

This generates:

infrastructure-catalog/
├── units/
│   ├── s3/terragrunt.hcl           # Wraps terraform-aws-s3 module
│   ├── dynamodb/terragrunt.hcl     # Wraps terraform-aws-dynamodb module
│   └── lambda/terragrunt.hcl       # Wraps terraform-aws-lambda module
└── stacks/
    └── serverless-api/terragrunt.stack.hcl  # Combines units

2. Create a Live Repository

# Ask your agent to scaffold a live repo
"Create a live infrastructure repo for AWS with staging environment"

This generates:

infrastructure-live/
├── root.hcl                        # Provider, backend, catalog config
├── non-prod/
│   ├── account.hcl                 # AWS account config
│   └── us-east-1/
│       ├── region.hcl
│       └── staging/
│           ├── env.hcl             # Environment config
│           └── my-api/
│               └── terragrunt.stack.hcl  # Deployment (references catalog)

3. Deploy

cd infrastructure-live/non-prod/us-east-1/staging/my-api

# Plan the stack
terragrunt stack run plan

# Apply the stack
terragrunt stack run apply

# Target specific unit using filters (recommended)
terragrunt stack run apply --filter '.terragrunt-stack/dynamodb'

# Target unit and its dependencies
terragrunt stack run apply --filter '.terragrunt-stack/lambda...'

See Terragrunt Filters for advanced filtering options. Stacks need Terragrunt 0.78+ and --filter needs 0.97+; on older versions use run-all with --terragrunt-include-dir.

Usage

The skill activates when working with:

terragrunt.hcl files (units)
terragrunt.stack.hcl files (stacks)
root.hcl configuration
Terragrunt CLI commands

Example Prompts

"Create a new EKS stack with Karpenter and ArgoCD registration"
"Set up a serverless API with Lambda, DynamoDB, and S3"
"Add GitLab CI pipeline with GCP Workload Identity"
"Optimize Terragrunt performance with provider caching"

Test Output (Examples)

The test-output/ directory contains example files generated using this skill, demonstrating the recommended patterns:

test-output/
├── catalog/                    # Example catalog repo structure
│   ├── units/
│   │   ├── s3/terragrunt.hcl
│   │   ├── dynamodb/terragrunt.hcl
│   │   └── lambda/terragrunt.hcl
│   └── stacks/
│       ├── serverless-api/terragrunt.stack.hcl
│       └── eks-cluster/terragrunt.stack.hcl
└── live/                       # Example live repo structure
    ├── root.hcl
    └── non-prod/
        ├── account.hcl
        └── us-east-1/
            ├── region.hcl
            └── staging/
                ├── env.hcl
                └── my-api/terragrunt.stack.hcl

Note: In production, catalog/ and live/ would be separate Git repositories. They are combined here for demonstration purposes only.

Documentation Structure

File	Description
`skills/terragrunt-skill/SKILL.md`	Core skill documentation
`test-output/`	Example output generated by this skill
`skills/terragrunt-skill/references/cicd-pipelines.md`	GitLab CI & GitHub Actions templates
`skills/terragrunt-skill/references/patterns.md`	Repository separation, pre-commit, semantic-release
`skills/terragrunt-skill/references/performance.md`	Caching, benchmarking, optimization
`skills/terragrunt-skill/references/state-management.md`	S3/DynamoDB backend patterns
`skills/terragrunt-skill/references/multi-account.md`	Cross-account deployment patterns
`skills/terragrunt-skill/references/version-compatibility.md`	Terragrunt 0.68→1.2 feature matrix, CLI mapping, OpenTofu vs Terraform

Compatibility

Terragrunt 0.68+ (examples target 1.2; explicit stacks need 0.78+, autoinclude 1.1+, expansion 1.2+, --filter 0.97+). See version-compatibility.md.
OpenTofu 1.6+ / Terraform 1.5+ (S3 use_lockfile: OpenTofu 1.10+ / Terraform 1.11+; state encryption is OpenTofu-only)
AWS, GCP (authentication patterns)

Contributing

See AGENTS.md for contributor guidelines and repository architecture.

State Backend Bootstrap

Terragrunt creates state backend resources (S3 bucket, plus DynamoDB table if configured) from the remote_state block:

# root.hcl
remote_state {
  backend = "s3"
  config = {
    bucket       = "tfstate-${local.account_name}-${local.aws_region}"
    key          = "${path_relative_to_include()}/terraform.tfstate"
    region       = local.aws_region
    encrypt      = true
    use_lockfile = true
  }
  generate = {
    path      = "backend.tf"
    if_exists = "overwrite_terragrunt"
  }
}

Run terragrunt backend bootstrap --all (Terragrunt 0.77+) or pass --backend-bootstrap to create the bucket (with versioning, encryption, access logging). Automatic provisioning was the default before 0.78, became opt-in in 0.78.0, and was removed in 0.87.0: Terragrunt now exits with an error instead. Native S3 lockfile (OpenTofu >= 1.10 / Terraform >= 1.11) replaces the need for a DynamoDB lock table.

See State Backend for details.

Platform Engineering & Self-Service

Catalog Discovery

The terragrunt catalog command enables self-service infrastructure by letting teams browse and scaffold from your catalog:

# Browse available modules, units, and stacks
terragrunt catalog

# Scaffold a specific unit
terragrunt scaffold git@github.com:YOUR_ORG/infrastructure-catalog.git//units/rds

Boilerplate Templates

Boilerplate powers the scaffolding with interactive prompts:

# units/rds/boilerplate.yml
variables:
  - name: instance_class
    description: "RDS instance class"
    type: string
    default: "db.t3.medium"

  - name: engine_version
    description: "Database engine version"
    type: string
    default: "15.4"

When users run terragrunt scaffold, they're prompted for these values, generating a pre-configured terragrunt.hcl.

Self-Service Portal Integration

The scaffold command can be integrated with internal developer platforms:

# API endpoint calls scaffold with predefined values
terragrunt scaffold \
  git@github.com:YOUR_ORG/infrastructure-catalog.git//units/rds \
  --var instance_class=db.r5.large \
  --var engine_version=15.4 \
  --output-folder /deployments/team-a/rds

This enables:

Standardized deployments across teams
Governance via catalog-level policies
Reduced toil through automated configuration
Version control with automatic Git tag resolution

References

License

Apache 2.0