direnv-skill_skill

Overview

This skill guides you through using direnv to manage directory-specific environment variables and per-project shells. It covers installation, shell hooks, .envrc patterns, stdlib functions, language layouts, Nix integration, secrets handling, and troubleshooting. You’ll get practical templates and commands to enforce safe, repeatable environments across macOS and Linux.

How this skill works

direnv hooks into your shell and detects .envrc files on directory change. When an .envrc is allowed, it runs in a subshell, captures exported variables, and applies them to your current shell; leaving the directory unloads those changes. The allowlist security model requires explicit approval with direnv allow and supports validation helpers like env_vars_required and direnv_version.

When to use it

• Installing or configuring direnv on macOS or Linux
• Creating or updating a project .envrc to manage env vars and PATH
• Configuring language-specific layouts (Python, Node, Ruby, Go, Perl)
• Integrating projects with Nix or Nix Flakes using use nix / use flake
• Managing secrets and local overrides without committing them to git
• Troubleshooting environment loading, hook installation, or performance issues

Best practices

• Keep secrets out of committed .envrc; use .envrc.local or environment secrets manager and gitignore them
• Prefer stdlib helpers (PATH_add, dotenv_if_exists, layout, use) over manual exports for reliability
• Add direnv hook to your shell config and place it after prompt/version managers; restart shell with exec $SHELL
• Commit a safe base .envrc and a .env.example template; ignore .direnv/ and local override files
• Use direnv_version and env_vars_required to enforce team consistency and fail fast
• Watch files that affect the environment (watch_file/watch_dir) to trigger reloads when dependencies change

Example use cases

• Project bootstrap: .envrc loads dotenv_if_exists, layout python3, PATH_add bin, and validates required vars
• Monorepo: root .envrc exports PROJECT_ROOT and services source_up to inherit common settings
• Nix Flakes: use flake ".#devShell" to enter a flake-provided dev environment; combine with nix-direnv for caching
• Language layouts: layout node or layout python3 to auto-manage node_modules/.bin or create virtualenvs under .direnv
• Secrets handling: store fallbacks in committed .envrc and actual secrets in .envrc.local or a secrets manager via custom use_aws_secrets