Environment Setup

---
name: environment-setup
description: "Environment Setup helps you configure runtimes, manage dependencies, and diagnose PATH and platform issues to reproduce a working dev environment quickly."
metadata:
  tags: "environment-setup, dev-environment, node-version-management, python-virtualenv, path-issues, troubleshooting, cross-platform"
  source: "https://skilldb.dev/skills/autonomous-agent-skills/environment-setup"
  pack: "autonomous-agent-skills"
  category: "Autonomous Agents"
---

# Environment Setup

## When to use this skill
Use when the user says things like:
- "I need to set up a fresh development environment."
- "Help me configure Node.js version management (nvm/fnm)."
- "I'm troubleshooting PATH or virtualenv issues."
- "Set up Python virtual environment and install requirements."
- "Diagnose cross-platform environment setup failures."


You are an AI agent helping set up and troubleshoot development environments. Your role is to configure runtimes, manage dependencies, resolve platform-specific issues, and diagnose common setup failures — getting developers from a fresh checkout to a working environment as quickly as possible.

## Philosophy

Environment setup is the first thing a developer does and the first thing that can go wrong. A broken environment blocks all other work. The goal is reproducibility: every developer should be able to set up a working environment from the same instructions, regardless of their operating system or prior configuration. When setup fails, the error messages are often misleading — the real cause is usually a missing dependency, a wrong version, or a PATH misconfiguration several steps upstream.

## Techniques

### Node.js Version Management
- Use version managers (nvm, fnm, volta) rather than global Node installs. Projects require specific Node versions, and global installs create conflicts.
- Check for `.nvmrc`, `.node-version`, or `volta` configuration in `package.json` to determine the required Node version.
- Run `nvm use` or `fnm use` in the project directory to switch to the correct version before installing dependencies.
- If `nvm` is not recognized, the shell profile (`.bashrc`, `.zshrc`, `.bash_profile`) may not be loading nvm's initialization script.
- On Windows, use `nvm-windows` (different from nvm for Unix) or `fnm` which works cross-platform.

### Python Virtual Environments
- Always use virtual environments (`venv`, `virtualenv`, `conda`) to isolate project dependencies from the system Python.
- Create the environment: `python -m venv .venv`. Activate it: `source .venv/bin/activate` (Unix) or `.venv\Scripts\activate` (Windows).
- Check for `requirements.txt`, `pyproject.toml`, `Pipfile`, or `setup.py` to determine how dependencies are managed.
- If `pip install` fails with compilation errors, the project likely needs system-level build tools: `build-essential` on Linux, Xcode CLI tools on Mac, Visual Studio Build Tools on Windows.
- Use `python --version` and `which python` (Unix) or `where python` (Windows) to verify the active interpreter is the expected one.

### Package Installation
- Read the project's setup documentation first. Many projects have specific installation steps beyond `npm install` or `pip install`.
- If `npm install` fails, check the Node version (too old or too new), try clearing the cache (`npm cache clean --force`), and check for native compilation dependencies.
- For lock file conflicts, use the package manager that matches the lock file: `package-lock.json` for npm, `yarn.lock` for yarn, `pnpm-lock.yaml` for pnpm.
- If dependencies fail to compile native modules, install the platform's build toolchain first.
- Use `--legacy-peer-deps` with npm only as a last resort — it hides real version conflicts.

### Platform-Specific Issues
- **Windows**: Line endings (CRLF vs LF) cause issues with shell scripts and git. Configure `git config core.autocrlf` appropriately. Use Git Bash or WSL for Unix-style tooling.
- **Windows**: Some npm packages use Unix shell commands in scripts. Use cross-platform alternatives (`cross-env`, `rimraf`) or run in WSL/Git Bash.
- **macOS**: After OS updates, Xcode CLI tools may need reinstalling: `xcode-select --install`. Homebrew packages may need relinking.
- **Linux**: Package names differ between distributions. Ubuntu/Debian use `apt`, Fedora/RHEL use `dnf`, Arch uses `pacman`.
- File path length limits on Windows can break deeply nested `node_modules`. Use pnpm (flat structure) or enable long paths in Windows.

### PATH Configuration
- When a command is "not found," it is almost always a PATH issue. The binary exists but the shell does not know where to find it.
- Check PATH with `echo $PATH` (Unix) or `echo %PATH%` (Windows cmd) or `$env:Path` (PowerShell).
- Version managers add their directories to PATH through shell profile scripts. If the profile is not loaded, the managed versions are invisible.
- On Unix, profile loading order matters: `.bash_profile` vs `.bashrc` vs `.zshrc`. Interactive vs login shells load different files.
- After modifying PATH, open a new terminal or `source` the profile file — the current terminal will not pick up changes.

### Environment Variable Management
- Check for `.env.example` or `.env.sample` files that document required environment variables.
- Copy the example file to `.env` and fill in values. Never commit `.env` files with real secrets.
- Use tools like `dotenv` to load `.env` files automatically during development.
- Some variables must be set at the system level (database connection strings, API keys) — `.env` files only work if the application loads them.
- When environment variables seem to not work, check for typos, extra whitespace, and quoting issues. `VAR= value` is different from `VAR=value`.

### Common Setup Failure Patterns
- **"Command not found"**: Missing binary or PATH misconfiguration. Install the tool or fix the PATH.
- **Permission denied**: On Unix, avoid `sudo npm install -g`. Fix npm's global directory permissions instead. On files, check execute permissions for scripts.
- **Version mismatch**: The installed version does not match what the project requires. Use a version manager.
- **Port already in use**: Another process (or a previous run) is using the port. Find and kill it, or change the port.
- **Module not found**: Dependencies not installed, wrong Node/Python version, or the virtual environment is not activated.
- **SSL/certificate errors**: Corporate proxies or VPNs intercept HTTPS. Configure the proxy or install the corporate CA certificate.

## Best Practices

- Document setup steps in the project README and keep them updated. Test the instructions on a clean machine periodically.
- Use lock files and commit them. They ensure everyone installs the same dependency versions.
- Provide a single setup command when possible (`make setup`, `./scripts/setup.sh`) that handles all steps.
- Use Docker for complex environments with many system dependencies — it eliminates "works on my machine."
- When troubleshooting, verify assumptions systematically: which binary is running, which version, which directory, which environment.

## Anti-Patterns

- **Installing globally**: Global installs create version conflicts between projects. Use project-local installs and version managers.
- **Using `sudo` for package managers**: Indicates a permissions problem. Fix the permissions rather than escalating privileges.
- **Skipping the README**: Setup documentation exists for a reason. Read it before improvising.
- **Ignoring lock files**: Installing without lock files produces different dependency trees on different machines.
- **Hardcoding absolute paths**: Paths like `/Users/john/project` break on other machines. Use relative paths and environment variables.
- **Not checking the required runtime version**: Installing dependencies with the wrong Node or Python version causes subtle failures.