---

name: varlock description: "Secure-by-default environment variable management for Claude Code sessions." risk: critical source: "https://github.com/dmno-dev/varlock" version: 1.0.0

Varlock Security Skill

Secure-by-default environment variable management for Claude Code sessions.

Repository: https://github.com/dmno-dev/varlock Documentation: https://varlock.dev

When to Use

• You need to work with environment variables or secrets in a Claude Code session without exposing their values.
• The task involves validating, loading, or auditing secrets while keeping them out of logs, diffs, and assistant context.
• You want a secure-by-default workflow built around Varlock instead of direct .env inspection.

Core Principle: Secrets Never Exposed

When working with Claude, secrets must NEVER appear in:

• Terminal output
• Claude's input/output context
• Log files or traces
• Git commits or diffs
• Error messages

This skill ensures all sensitive data is properly protected.

---

CRITICAL: Security Rules for Claude

Rule 1: Never Echo Secrets

# ❌ NEVER DO THIS - exposes secret to Claude's context
echo $CLERK_SECRET_KEY
cat .env | grep SECRET
printenv | grep API

# ✅ DO THIS - validates without exposing
varlock load --quiet && echo "✓ Secrets validated"

Rule 2: Never Read .env Directly

# ❌ NEVER DO THIS - exposes all secrets
cat .env
less .env
Read tool on .env file

# ✅ DO THIS - read schema (safe) not values
cat .env.schema
varlock load  # Shows masked values

Rule 3: Use Varlock for Validation

# ❌ NEVER DO THIS - exposes secret in error
test -n "$API_KEY" && echo "Key: $API_KEY"

# ✅ DO THIS - Varlock validates and masks
varlock load
# Output shows: API_KEY 🔐sensitive └ ▒▒▒▒▒

Rule 4: Never Include Secrets in Commands

# ❌ NEVER DO THIS - secret in command history
curl -H "Authorization: Bearer sk_live_xxx" https://api.example.com

# ✅ DO THIS - use environment variable
curl -H "Authorization: Bearer $API_KEY" https://api.example.com
# Or better: varlock run -- curl ...

---

Quick Start

Installation

# Install Varlock CLI
curl -sSfL https://varlock.dev/install.sh -o /tmp/varlock-install.sh
sed -n '1,160p' /tmp/varlock-install.sh
sh /tmp/varlock-install.sh --force-no-brew

# Add to PATH (add to ~/.zshrc or ~/.bashrc)
export PATH="$HOME/.varlock/bin:$PATH"

# Verify
varlock --version

Initialize Project

# Create .env.schema from existing .env
varlock init

# Or create manually
touch .env.schema

---

Schema File: .env.schema

The schema defines types, validation, and sensitivity for each variable.

Basic Structure

# Global defaults
# @defaultSensitive=true @defaultRequired=infer

# Application
# @type=enum(development,staging,production) @sensitive=false
NODE_ENV=development

# @type=port @sensitive=false
PORT=3000

# Database - SENSITIVE
# @type=url @required
DATABASE_URL=

# @type=string @required @sensitive
DATABASE_PASSWORD=

# API Keys - SENSITIVE
# @type=string(startsWith=sk_) @required @sensitive
STRIPE_SECRET_KEY=

# @type=string(startsWith=pk_) @sensitive=false
STRIPE_PUBLISHABLE_KEY=

Security Annotations

| Annotation | Effect | Use For | |------------|--------|---------| | @sensitive | Redacted in all output | API keys, passwords, tokens | | @sensitive=false | Shown in logs | Public keys, non-secret config | | @defaultSensitive=true | All vars sensitive by default | High-security projects |

Type Annotations

| Type | Validates | Example | |------|-----------|---------| | string | Any string | @type=string | | string(startsWith=X) | Prefix validation | @type=string(startsWith=sk_) | | string(contains=X) | Substring validation | @type=string(contains=+clerk_test) | | url | Valid URL | @type=url | | port | 1-65535 | @type=port | | boolean | true/false | @type=boolean | | enum(a,b,c) | One of values | @type=enum(dev,prod) |

---

Safe Commands for Claude

Validating Environment

# Check all variables (safe - masks sensitive values)
varlock load

# Quiet mode (no output on success)
varlock load --quiet

# Check specific environment
varlock load --env=production

Running Commands with Secrets

# Inject validated env into command
varlock run -- npm start
varlock run -- node script.js
varlock run -- pytest

# Secrets are available to the command but never printed

Checking Schema (Safe)

# Schema is safe to read - contains no values
cat .env.schema

# List expected variables
grep "^[A-Z]" .env.schema

---

Common Patterns

Pattern 1: Validate Before Operations

# Always validate environment first
varlock load --quiet || {
  echo "❌ Environment validation failed"
  exit 1
}

# Then proceed with operation
npm run build

Pattern 2: Safe Secret Rotation

# 1. Update secret in external source (1Password, AWS, etc.)
# 2. Update .env file