Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIDeepSeekDeepSeekMuseMuse+22 more

    Env Doctor: Fix "It Won't Run on My Machine"

    3

    Agents often "fix" them with `sudo`, `--force`, deleted lockfiles or disabled TLS.

    Free

    11 uses5.0 (1 review)
    Env Doctor: Fix "It Won't Run on My Machine"

    Env Doctor: Fix "It Won't Run on My Machine"

    Example session with this skill installed

    I just cloned our backend repo and pnpm dev fails. It works on my colleague's machine. Fix it.

    • Read your context and instructions
    • Compiled the env doctor

    Scan (read-only)

    Required: .nvmrc 20 · engines node >=20 <21 · packageManager pnpm@9.12.0
    Installed: node v22.11.0 · pnpm (not found) · npm 10.9.0
    Lockfiles: pnpm-lock.yaml, package-lock.json   WARNING: multiple JS lockfiles
    .env: missing DATABASE_URL, REDIS_URL · empty: STRIPE_SECRET_KEY
    Ports: 5432 in use by postgres (pid 812) · Docker: running
    

    Root cause (3 issues)

    1. pnpm not enabled + Node 22 instead of 20 - first real error: ERR_PNPM_UNSUPPORTED_ENGINE
    2. .env incomplete - DATABASE_URL and REDIS_URL missing (only in .env.example)
    3. Port 5432 taken by a local Postgres, so docker compose up db fails to bind

    package-lock.json is stray (created by someone running npm i); CI uses pnpm.

    Fixes applied

    nvm install 20 && nvm use        # reads .nvmrc
    corepack enable                  # provides pnpm@9.12.0 from packageManager
    pnpm install --frozen-lockfile
    
    • Added DATABASE_URL and REDIS_URL to .env with the local compose values from .env.example
    • Port: you chose to keep your local Postgres, so the compose DB now maps to 5433:5432 and DATABASE_URL uses 5433 (didn't kill anything)
    • Left STRIPE_SECRET_KEY empty - you need to paste your test key (sk_test_...)
    • Asked before removing package-lock.json -> removed and added to .gitignore

    Proof

    pnpm build    ✓ built in 14.2s
    pnpm test     ✓ 312 passed
    pnpm dev      ✓ API listening on :3000
    curl :3000/health -> {"status":"ok","db":"up","redis":"up"}
    

    Prevent it

    • Add "doctor": "bash scripts/env_scan.sh" to package.json
    • .npmrc with engine-strict=true
    • README Getting started: nvm use && corepack enable && pnpm i
    Add to package.json

    Connects securely to your tools. The creator never sees your data.

    About this skill

    From "it doesn't run" to running, in minutes

    Setup failures waste hours: wrong Node version, missing env vars, a port already in use, a native module that won't compile. Agents often "fix" them with sudo, --force, deleted lockfiles or disabled TLS. Env Doctor finds the real cause and applies the smallest safe fix.

    What it does

    • Reads what the project expects: README, .nvmrc, engines, packageManager, .python-version, go.mod, Docker/compose, .env.example and CI config (the real source of truth).
    • Read-only scan with the included env_scan.sh: OS, required vs installed versions, lockfile conflicts, missing/empty .env keys (names only, never values), busy dev ports, Docker daemon, git state, disk space.
    • Reproduces the failure and reads the first real error, then maps it with a symptom-cause-fix table (node-gyp, EADDRINUSE, ECONNREFUSED, EBADENGINE, externally-managed Python, corporate CA certificates, EACCES, CRLF, client env prefixes, Apple Silicon images, OOM builds...).
    • Minimal, explained fixes using version managers, corepack and lockfile-faithful installs. Asks before killing processes or deleting caches; never sudo-installs globally, chmod 777, disables TLS or upgrades majors silently.
    • Proves it: install, build, test and start pass, with output.
    • Prevents the next one: version pins, complete .env.example, a doctor script, README and devcontainer suggestions.

    Great for onboarding new developers and "works on my colleague's machine" moments.

    Includes

    • SKILL.md workflow
    • scripts/env_scan.sh - tested read-only scanner (macOS/Linux/WSL)
    • references/diagnosis.md - 18 common symptoms with causes and safe fixes

    Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI and any SKILL.md-compatible agent.

    Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Testing & Debugging.

    Cannot generate actual secrets/API keys. Requires manual approval for killing processes or deleting caches. Best suited for standard package managers and containerized setups.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before buying a skill.

    Reviews

    5.0
    1 review
    5
    1
    4
    0
    3
    0
    2
    0
    1
    0

    This skill has been used 11 times.

    Trust & safety

    Security scan

    Security scan passed 9 days ago

    • Free with an Agensi account

    Software
    PythonGit

    Permissions

    Terminal / Shell
    Read Files
    Listed9 days ago
    Updated5 days ago

    What's inside

    Frequently Asked Questions

    The skill scans project-specific files like `.nvmrc`, `pyproject.toml`, and `.env.example` to establish a baseline of what your environment *should* look like before diagnosing deviations.

    No, this skill is designed to work with your existing local setup; it supports major version managers like nvm, pyenv, and uv to switch runtimes within your current shell environment.

    The skill prioritizes non-destructive, scoped fixes; it will always prompt for your explicit permission before performing actions like killing a process on a blocked port or clearing global caches.

    While it cannot generate actual secret keys, it identifies exactly which keys are missing from your `.env` file and creates templates to show you exactly what needs to be populated to get the app running.

    Yes, it is designed for cross-platform utility, identifying architecture-specific issues (like Rosetta vs. Native ARM) and OS-level runtime discrepancies for Node.js, Python, Go, and Rust.

    New in Testing & Debugging

    Free