Secure environment variable management with Varlock. Use when handling secrets, API keys, credentials, or any sensitive configuration. Ensures secrets are never exposed in terminals, logs, traces, or Claude's context. Trigger phrases include "environment variables", "secrets", ".env", "API key", "credentials", "sensitive", "Varlock".
Add this skill
npx mdskills install wrsmith108/varlockComprehensive security-first skill with clear rules, safe patterns, and actionable guidance for protecting secrets
1---2name: varlock3description: Secure environment variable management with Varlock. Use when handling secrets, API keys, credentials, or any sensitive configuration. Ensures secrets are never exposed in terminals, logs, traces, or Claude's context. Trigger phrases include "environment variables", "secrets", ".env", "API key", "credentials", "sensitive", "Varlock".4---56# Varlock Security Skill78Secure-by-default environment variable management for Claude Code sessions.910> **Repository**: https://github.com/dmno-dev/varlock11> **Documentation**: https://varlock.dev1213## Core Principle: Secrets Never Exposed1415When working with Claude, secrets must NEVER appear in:16- Terminal output17- Claude's input/output context18- Log files or traces19- Git commits or diffs20- Error messages2122This skill ensures all sensitive data is properly protected.2324---2526## CRITICAL: Security Rules for Claude2728### Rule 1: Never Echo Secrets2930```bash31# ❌ NEVER DO THIS - exposes secret to Claude's context32echo $CLERK_SECRET_KEY33cat .env | grep SECRET34printenv | grep API3536# ✅ DO THIS - validates without exposing37varlock load --quiet && echo "✓ Secrets validated"38```3940### Rule 2: Never Read .env Directly4142```bash43# ❌ NEVER DO THIS - exposes all secrets44cat .env45less .env46Read tool on .env file4748# ✅ DO THIS - read schema (safe) not values49cat .env.schema50varlock load # Shows masked values51```5253### Rule 3: Use Varlock for Validation5455```bash56# ❌ NEVER DO THIS - exposes secret in error57test -n "$API_KEY" && echo "Key: $API_KEY"5859# ✅ DO THIS - Varlock validates and masks60varlock load61# Output shows: API_KEY 🔐sensitive └ ▒▒▒▒▒62```6364### Rule 4: Never Include Secrets in Commands6566```bash67# ❌ NEVER DO THIS - secret in command history68curl -H "Authorization: Bearer sk_live_xxx" https://api.example.com6970# ✅ DO THIS - use environment variable71curl -H "Authorization: Bearer $API_KEY" https://api.example.com72# Or better: varlock run -- curl ...73```7475---7677## Quick Start7879### Installation8081```bash82# Install Varlock CLI83curl -sSfL https://varlock.dev/install.sh | sh -s -- --force-no-brew8485# Add to PATH (add to ~/.zshrc or ~/.bashrc)86export PATH="$HOME/.varlock/bin:$PATH"8788# Verify89varlock --version90```9192### Initialize Project9394```bash95# Create .env.schema from existing .env96varlock init9798# Or create manually99touch .env.schema100```101102---103104## Schema File: .env.schema105106The schema defines types, validation, and sensitivity for each variable.107108### Basic Structure109110```bash111# Global defaults112# @defaultSensitive=true @defaultRequired=infer113114# Application115# @type=enum(development,staging,production) @sensitive=false116NODE_ENV=development117118# @type=port @sensitive=false119PORT=3000120121# Database - SENSITIVE122# @type=url @required123DATABASE_URL=124125# @type=string @required @sensitive126DATABASE_PASSWORD=127128# API Keys - SENSITIVE129# @type=string(startsWith=sk_) @required @sensitive130STRIPE_SECRET_KEY=131132# @type=string(startsWith=pk_) @sensitive=false133STRIPE_PUBLISHABLE_KEY=134```135136### Security Annotations137138| Annotation | Effect | Use For |139|------------|--------|---------|140| `@sensitive` | Redacted in all output | API keys, passwords, tokens |141| `@sensitive=false` | Shown in logs | Public keys, non-secret config |142| `@defaultSensitive=true` | All vars sensitive by default | High-security projects |143144### Type Annotations145146| Type | Validates | Example |147|------|-----------|---------|148| `string` | Any string | `@type=string` |149| `string(startsWith=X)` | Prefix validation | `@type=string(startsWith=sk_)` |150| `string(contains=X)` | Substring validation | `@type=string(contains=+clerk_test)` |151| `url` | Valid URL | `@type=url` |152| `port` | 1-65535 | `@type=port` |153| `boolean` | true/false | `@type=boolean` |154| `enum(a,b,c)` | One of values | `@type=enum(dev,prod)` |155156---157158## Safe Commands for Claude159160### Validating Environment161162```bash163# Check all variables (safe - masks sensitive values)164varlock load165166# Quiet mode (no output on success)167varlock load --quiet168169# Check specific environment170varlock load --env=production171```172173### Running Commands with Secrets174175```bash176# Inject validated env into command177varlock run -- npm start178varlock run -- node script.js179varlock run -- pytest180181# Secrets are available to the command but never printed182```183184### Checking Schema (Safe)185186```bash187# Schema is safe to read - contains no values188cat .env.schema189190# List expected variables191grep "^[A-Z]" .env.schema192```193194---195196## Common Patterns197198### Pattern 1: Validate Before Operations199200```bash201# Always validate environment first202varlock load --quiet || {203 echo "❌ Environment validation failed"204 exit 1205}206207# Then proceed with operation208npm run build209```210211### Pattern 2: Safe Secret Rotation212213```bash214# 1. Update secret in external source (1Password, AWS, etc.)215# 2. Update .env file manually (don't use Claude for this)216# 3. Validate new value works217varlock load218219# 4. If using GitHub Secrets, sync (values not shown)220./scripts/update-github-secrets.sh221```222223### Pattern 3: CI/CD Integration224225```yaml226# GitHub Actions - secrets from GitHub Secrets227- name: Validate environment228 env:229 DATABASE_URL: ${{ secrets.DATABASE_URL }}230 API_KEY: ${{ secrets.API_KEY }}231 run: varlock load --quiet232```233234### Pattern 4: Docker Integration235236```dockerfile237# Install Varlock in container238RUN curl -sSfL https://varlock.dev/install.sh | sh -s -- --force-no-brew \239 && ln -s /root/.varlock/bin/varlock /usr/local/bin/varlock240241# Validate at container start242CMD ["varlock", "run", "--", "npm", "start"]243```244245---246247## Handling Secret-Related Tasks248249### When User Asks to "Check if API key is set"250251```bash252# ✅ Safe approach253varlock load 2>&1 | grep "API_KEY"254# Shows: ✅ API_KEY 🔐sensitive └ ▒▒▒▒▒255256# ❌ Never do257echo $API_KEY258```259260### When User Asks to "Debug authentication"261262```bash263# ✅ Safe approach - check presence and format264varlock load # Validates types and required fields265266# Check if key has correct prefix (without showing value)267varlock load 2>&1 | grep -E "(CLERK|AUTH)"268269# ❌ Never do270printenv | grep KEY271```272273### When User Asks to "Update a secret"274275```276Claude should respond:277"I cannot directly modify secrets for security reasons. Please:2781. Update the value in your .env file manually2792. Or update in your secrets manager (1Password, AWS, etc.)2803. Then run `varlock load` to validate281282I can help you update the .env.schema if you need to add new variables."283```284285### When User Asks to "Show me the .env file"286287```288Claude should respond:289"I won't read .env files directly as they contain secrets. Instead:290- Run `varlock load` to see masked values291- Run `cat .env.schema` to see the schema (safe)292- I can help you modify .env.schema if needed"293```294295---296297## External Secret Sources298299### 1Password Integration300301```bash302# In .env.schema303# @type=string @sensitive304API_KEY=exec('op read "op://vault/item/field"')305```306307### AWS Secrets Manager308309```bash310# In .env.schema311# @type=string @sensitive312DB_PASSWORD=exec('aws secretsmanager get-secret-value --secret-id prod/db')313```314315### Environment-Specific Values316317```bash318# In .env.schema319# @type=url320API_URL=env('API_URL_${NODE_ENV}', 'http://localhost:3000')321```322323---324325## Troubleshooting326327### "varlock: command not found"328329```bash330# Check installation331ls ~/.varlock/bin/varlock332333# Add to PATH334export PATH="$HOME/.varlock/bin:$PATH"335336# Or use full path337~/.varlock/bin/varlock load338```339340### "Schema validation failed"341342```bash343# Check which variables are missing/invalid344varlock load # Shows detailed errors345346# Common fixes:347# - Add missing required variables to .env348# - Fix type mismatches (port must be number)349# - Check string prefixes match schema350```351352### "Sensitive value exposed in logs"353354```bash355# 1. Rotate the exposed secret immediately356# 2. Check .env.schema has @sensitive annotation357# 3. Ensure using varlock commands, not echo/cat358359# Add missing sensitivity:360# Before: API_KEY=361# After: # @type=string @sensitive362# API_KEY=363```364365---366367## npm Scripts368369Add these to your package.json:370371```json372{373 "scripts": {374 "env:validate": "varlock load",375 "env:check": "varlock load --quiet || echo 'Environment validation failed'",376 "prestart": "varlock load --quiet",377 "start": "varlock run -- node server.js"378 }379}380```381382---383384## Security Checklist for New Projects385386- [ ] Install Varlock CLI387- [ ] Create `.env.schema` with all variables defined388- [ ] Mark all secrets with `@sensitive` annotation389- [ ] Add `@defaultSensitive=true` to schema header390- [ ] Add `.env` to `.gitignore`391- [ ] Commit `.env.schema` to version control392- [ ] Add `npm run env:validate` to CI/CD393- [ ] Document secret rotation procedure394- [ ] Never use `cat .env` or `echo $SECRET` in Claude sessions395396---397398## Quick Reference Card399400| Task | Safe Command |401|------|-------------|402| Validate all env vars | `varlock load` |403| Quiet validation | `varlock load --quiet` |404| Run with env | `varlock run -- <cmd>` |405| View schema | `cat .env.schema` |406| Check specific var | `varlock load \| grep VAR_NAME` |407408| Never Do | Why |409|----------|-----|410| `cat .env` | Exposes all secrets |411| `echo $SECRET` | Exposes to Claude context |412| `printenv \| grep` | Exposes matching secrets |413| Read .env with tools | Secrets in Claude's context |414| Hardcode in commands | In shell history |415416---417418## Integration with Other Skills419420### Clerk Skill421- Test user passwords are `@sensitive`422- Test emails are `@sensitive=false` (contain +clerk_test, not secret)423- See: `~/.claude/skills/clerk/SKILL.md`424425### Docker Skill426- Mount `.env` file, never copy secrets to image427- Use `varlock run` as entrypoint428- See: `~/.claude/skills/docker/SKILL.md`429430---431432*Last updated: December 22, 2025*433*Secure-by-default environment management for Claude Code*434
Full transparency — inspect the skill content before installing.