# Env Doctor

> Env Doctor

- Skill: `comcclelland/env-doctor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add comcclelland/env-doctor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/comcclelland/env-doctor/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: comcclelland (https://skillmd.com/u/comcclelland)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/comcclelland/env-doctor

---

# Env Doctor

Diagnoses project environment and startup failures systematically.

## When to Use

- When the user says "it won't start", "I'm getting errors", "my environment is broken"
- When a build, test, or dev server fails unexpectedly
- When setting up a project on a new machine

## Process

1. **Identify the failure**: Read the error output carefully
2. **Check prerequisites**:
   - Runtime versions (Node.js, Python, Go, etc.) — compare to project requirements
   - Package manager state (`node_modules` exists? `venv` activated?)
   - Required environment variables (check `.env.example`, `.env`, config files)
   - Required system tools (git, sqlite3, docker, etc.)
   - Required services (database, Redis, API keys)

3. **Diagnose common issues**:
   - Missing dependencies → suggest install command
   - Version mismatch → show required vs actual
   - Missing env vars → list what's needed and where to get values
   - Port conflicts → identify what's using the port
   - Permission errors → identify the restricted resource
   - Stale cache/build artifacts → suggest clean commands

4. **Report findings** in this format:
   ```
   ❌ Problem: [what's wrong]
   💡 Cause: [why it's happening]
   ✅ Fix: [exact command or step to resolve]
   ```

5. **Offer to fix**: If the fix is safe and reversible, offer to run it

### Rules
- Check the simplest causes first (missing install, wrong directory, typo)
- Never suggest destructive fixes without confirmation
- If multiple issues exist, fix them in dependency order
- Verify the fix worked before moving on