Environment Setup Guide Skill

A Claude Code skill for guiding developers through complete development environment setup — from installing tools and configuring dependencies to setting up databases, environment variables, and IDE settings.

When to Use This Skill

Choose this skill when:

• Onboarding a new developer to the project
• Setting up a development environment on a new machine
• Configuring project-specific tools and dependencies
• Troubleshooting environment issues (wrong versions, missing tools)
• Creating reproducible setup documentation for a team
• Migrating development environment to a new OS or platform

Consider alternatives when:

• You need Docker-based development environments (use a Docker skill)
• You need cloud development environments (use Codespaces/Gitpod)
• You need CI/CD environment configuration (use a CI skill)

Quick Start

Copy
# Add to your Claude Code project
claude mcp add environment-setup

# Set up development environment from scratch
claude "set up the complete development environment for this project"

# Verify current setup
claude "check if my development environment is correctly configured"

Copy
# .claude/skills/environment-setup.yml
name: environment-setup
description: Guide developers through complete environment setup
triggers:
  - "setup environment"
  - "dev setup"
  - "onboarding"
config:
  platform: auto
  verify_after_install: true
  include_ide: true

Core Concepts

Setup Checklist

Category	Tools	Verification
Runtime	Node.js, Python, Go	node -v, python --version
Package Manager	npm, pip, pnpm	npm -v, pip --version
Version Manager	nvm, pyenv, asdf	nvm current, pyenv version
Database	PostgreSQL, Redis, MongoDB	pg_isready, redis-cli ping
IDE	VSCode extensions, settings	Extension list, settings.json
Environment	.env files, API keys	App starts without errors
Git	Hooks, config, SSH keys	git status, ssh -T [email protected]

Automated Setup Script

Copy
#!/bin/bash
# scripts/setup.sh — One-command development setup
set -euo pipefail

echo "=== Checking prerequisites ==="

# Check Node.js version
REQUIRED_NODE="20"
CURRENT_NODE=$(node -v 2>/dev/null | cut -d. -f1 | tr -d 'v' || echo "0")
if [ "$CURRENT_NODE" -lt "$REQUIRED_NODE" ]; then
  echo "Node.js $REQUIRED_NODE+ required. Install via nvm:"
  echo "  nvm install $REQUIRED_NODE && nvm use $REQUIRED_NODE"
  exit 1
fi

echo "=== Installing dependencies ==="
npm ci

echo "=== Setting up environment ==="
if [ ! -f .env ]; then
  cp .env.example .env
  echo "Created .env from .env.example — fill in your API keys"
fi

echo "=== Setting up database ==="
npm run db:migrate
npm run db:seed

echo "=== Installing git hooks ==="
npx husky install

echo "=== Verifying setup ==="
npm run typecheck
npm test -- --bail

echo "✓ Development environment is ready!"
echo "  Run 'npm run dev' to start the development server"

Environment Variables Management

Copy
# .env.example — Template with descriptions
# Database
DATABASE_URL=postgresql://localhost:5432/myapp_dev  # Local dev database
REDIS_URL=redis://localhost:6379                     # Local Redis instance

# Authentication (get from team vault)
JWT_SECRET=                    # Generate with: openssl rand -hex 32
CLERK_SECRET_KEY=              # From Clerk dashboard

# External Services (optional for local dev)
STRIPE_SECRET_KEY=             # Test mode key from Stripe dashboard
SENDGRID_API_KEY=              # For email testing

Configuration

Parameter	Type	Default	Description
platform	string	"auto"	Target platform: auto, macos, linux, windows
verify_after_install	boolean	true	Run verification checks after each install step
include_ide	boolean	true	Include IDE (VSCode) setup instructions
include_git_hooks	boolean	true	Set up pre-commit hooks
database_setup	boolean	true	Include database migration and seeding
use_version_manager	boolean	true	Install runtimes via nvm/pyenv instead of system packages
create_env_file	boolean	true	Copy .env.example to .env if not exists

Best Practices

1. Provide a single setup.sh script — new developers should run one command to get a working environment; every manual step is a potential support ticket.

2. Use version managers (nvm, pyenv) not system installs — version managers let developers switch between projects with different runtime requirements without conflicts.

3. Ship a .env.example file with descriptive comments — document every required environment variable with where to get the value; never commit actual secrets to the repository.

4. Verify each setup step automatically — after installing a tool, verify it works (node -v, pg_isready); catching failures during setup is far easier than debugging runtime errors later.

5. Document platform-specific differences — if macOS needs brew install postgresql while Ubuntu needs apt install postgresql, document both; developers shouldn't have to figure out platform translations.

Common Issues

Node.js version mismatch between developers — Different versions cause subtle behavior differences. Add an .nvmrc file with the exact version and a engines field in package.json; the setup script should verify the version matches.

Database connection refused during setup — PostgreSQL or Redis isn't running. Add a check in the setup script: pg_isready || echo "Start PostgreSQL first: brew services start postgresql" with platform-specific start instructions.

Missing environment variables cause cryptic errors — The app crashes with Cannot read property of undefined instead of saying which variable is missing. Add startup validation that checks all required variables and exits with a clear message listing what's missing.