AgentSkillsCN

env-manager

在本地开发环境、CI/CD 流水线以及部署平台之间，实现环境变量的全面校验、同步与高效管理。

SKILL.md
--- frontmatter
name: env-manager
description: Environment variable validation, synchronization, and management across local development, CI/CD, and deployment platforms
version: 1.0.0
category: infrastructure
progressive_disclosure:
  entry_point:
    summary: "Validate, synchronize, and secure environment variables across local dev, CI/CD, and deployment platforms with framework-specific support"
    when_to_use: "When managing .env files, deploying to Vercel/Railway/Heroku, syncing with secret managers, or troubleshooting env-related issues"
    quick_start: "1. Validate local .env 2. Check security 3. Sync to platform 4. Verify deployment 5. Generate documentation"
  references:
    - validation.md
    - security.md
    - synchronization.md
    - frameworks.md
    - troubleshooting.md
author: Claude MPM Team
license: MIT
requires_tools:
  - bash
  - python
tags:
  - environment-variables
  - deployment
  - security
  - devops
  - nextjs
  - vercel
  - railway
context_limit: 800

Environment Variable Manager

Overview

Manage environment variables systematically across local development, CI/CD pipelines, and deployment platforms. Prevent common issues like missing variables, exposed secrets, platform misconfigurations, and framework-specific gotchas.

Core capabilities:

  • •Validation: Check structure, completeness, naming conventions
  • •Security: Scan for exposed secrets, validate .gitignore coverage
  • •Synchronization: Sync with deployment platforms and secret managers
  • •Framework Support: Next.js, Express, Flask, Django patterns
  • •Documentation: Auto-generate .env.example and setup guides

When to Use This Skill

Activate when:

  • •Setting up new project environment configuration
  • •Deploying to Vercel, Railway, Heroku, or other platforms
  • •Troubleshooting "works locally but not in production"
  • •Managing secrets across multiple environments
  • •Syncing variables with 1Password, AWS Secrets Manager
  • •Creating .env.example documentation
  • •Onboarding new developers (environment setup)
  • •Migrating between deployment platforms
  • •Framework-specific env configuration (Next.js NEXT_PUBLIC_ prefix)

Core Principles

  1. •Never Log Secrets: All operations must NEVER display actual secret values
  2. •Validate Before Deploy: Catch env issues locally, not in production
  3. •Framework-Aware: Respect framework conventions (Next.js, Express, Flask)
  4. •Platform-Specific: Generate correct configs for each deployment platform
  5. •Security First: Scan for exposed secrets, validate .gitignore

Quick Start

Validation Workflow

bash
# 1. Check local .env structure
python scripts/validate_env.py .env

# 2. Check for missing variables
python scripts/validate_env.py .env --compare .env.example

# 3. Validate naming conventions
python scripts/validate_env.py .env --framework nextjs

# 4. Check for duplicates
python scripts/validate_env.py .env --check-duplicates

Security Workflow

bash
# 1. Scan for exposed secrets in code
python scripts/scan_exposed.py --scan-code

# 2. Check .gitignore coverage
python scripts/scan_exposed.py --check-gitignore

# 3. Validate secret formats
python scripts/scan_exposed.py --validate-formats .env

Synchronization Workflow

bash
# 1. Compare local vs platform
python scripts/sync_secrets.py --platform vercel --compare

# 2. Generate platform config
python scripts/sync_secrets.py --platform vercel --generate

# 3. Sync to platform (dry-run first)
python scripts/sync_secrets.py --platform vercel --sync --dry-run

# 4. Actual sync
python scripts/sync_secrets.py --platform vercel --sync

Documentation Workflow

bash
# Generate .env.example from .env
python scripts/validate_env.py .env --generate-example

# Generate setup documentation
python scripts/validate_env.py .env --generate-docs

Navigation

For detailed workflows and patterns:

  • •Validation: Complete validation workflows and checks
  • •Security: Secret scanning and security patterns
  • •Synchronization: Platform sync and secret manager integration
  • •Frameworks: Framework-specific patterns (Next.js, Express, Flask)
  • •Troubleshooting: Common issues and solutions

Framework-Specific Quick Reference

Next.js

bash
# Validate Next.js env structure
# - NEXT_PUBLIC_* for client-side vars
# - Check .env.local, .env.production precedence
python scripts/validate_env.py .env --framework nextjs

# Files to manage:
# - .env.local (local development, gitignored)
# - .env.production (production, usually from platform)
# - .env (shared defaults, committed)
# - .env.example (documentation, committed)

Express/Node.js

bash
# Validate Node.js env structure
python scripts/validate_env.py .env --framework nodejs

# Standard structure:
# - process.env.NODE_ENV
# - process.env.PORT
# - process.env.DATABASE_URL

Python/Flask

bash
# Validate Python env structure
python scripts/validate_env.py .env --framework python

# Standard structure:
# - FLASK_APP
# - FLASK_ENV
# - DATABASE_URL (SQLAlchemy format)

Platform-Specific Quick Reference

Vercel

bash
# Generate vercel.json env config
python scripts/sync_secrets.py --platform vercel --generate

# Sync to Vercel project
python scripts/sync_secrets.py --platform vercel --sync

# Respects NEXT_PUBLIC_ prefix for client-side vars

Railway

bash
# Generate Railway config
python scripts/sync_secrets.py --platform railway --generate

# Sync to Railway project
python scripts/sync_secrets.py --platform railway --sync

Heroku

bash
# Generate Heroku config
python scripts/sync_secrets.py --platform heroku --generate

# Sync via Heroku CLI
python scripts/sync_secrets.py --platform heroku --sync

Key Reminders

  • •NEVER log actual secret values - Always mask/redact in output
  • •Validate before every deployment - Catch issues locally
  • •Use .env.example for documentation - Keep it updated
  • •Framework conventions matter - Next.js NEXT_PUBLIC_, Django DJANGO_SETTINGS_MODULE
  • •Platform-specific quirks exist - Vercel auto-exposes NEXT_PUBLIC_*, Railway uses exact syntax
  • •Secret managers are your friend - 1Password, AWS Secrets Manager for team sync
  • •.gitignore is critical - NEVER commit .env files with secrets
  • •Environment precedence can be tricky - Know your framework's loading order

Common Validation Checks

Structure Validation

  • • No empty values (except explicitly allowed)
  • • No inline comments (some parsers don't support)
  • • Proper quoting for values with spaces
  • • No duplicate keys
  • • Valid key naming (UPPERCASE_WITH_UNDERSCORES)

Security Validation

  • • No exposed secrets in code
  • • .env files in .gitignore
  • • No secrets in git history
  • • API keys match expected format
  • • No hardcoded URLs with credentials

Framework Validation (Next.js)

  • • NEXT_PUBLIC_* for client-side vars only
  • • No secrets in NEXT_PUBLIC_* vars
  • • .env.local exists for local secrets
  • • .env.example documents all vars

Platform Validation (Vercel)

  • • All required vars defined
  • • No conflicts between environments
  • • Correct variable names (Vercel conventions)
  • • Build-time vs runtime vars separated

Integration with Other Skills

Related Skills

  • •docker-containerization - Environment variables in containers
  • •security-scanning - Broader security checks including secrets
  • •nextjs-local-dev - Next.js specific development patterns
  • •systematic-debugging - Debug env-related issues

Workflow Integration

code
1. Developer creates .env.local
2. env-manager validates structure
3. env-manager scans for security issues
4. Developer generates .env.example
5. Before deploy: env-manager compares local vs platform
6. env-manager generates platform config
7. Developer reviews and confirms sync
8. env-manager syncs to platform
9. Deployment proceeds with verified configuration

Lines: 197 (including frontmatter) ✓ <200