- Home
- Skills
- Testing & Debugging
- Env Doctor: Fix "It Won't Run on My Machine"
Works with the AI Agents you already use
Env Doctor: Fix "It Won't Run on My Machine"
Agents often "fix" them with `sudo`, `--force`, deleted lockfiles or disabled TLS.
Free
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)
- pnpm not enabled + Node 22 instead of 20 - first real error:
ERR_PNPM_UNSUPPORTED_ENGINE .envincomplete -DATABASE_URLandREDIS_URLmissing (only in.env.example)- Port 5432 taken by a local Postgres, so
docker compose up dbfails 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_URLandREDIS_URLto.envwith the local compose values from.env.example - Port: you chose to keep your local Postgres, so the compose DB now maps to
5433:5432andDATABASE_URLuses 5433 (didn't kill anything) - Left
STRIPE_SECRET_KEYempty - 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 .npmrcwithengine-strict=true- README Getting started:
nvm use && corepack enable && pnpm i
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.exampleand 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.envkeys (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, adoctorscript, 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.
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
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
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
This skill has been used 11 times.
Trust & safety
Security scan
Security scan passed 9 days ago
- Free with an Agensi account
Requires