- Home
- Skills
- Testing & Debugging
- First Run Doctor
Works with the AI Agents you already use
First Run Doctor
Diagnose broken repository onboarding and generate verified, host-specific setup guides.
Free
First Run Doctor
Example session with this skill installed
Run the first-run doctor on this repo to see why the new dev can't start the app. They are seeing version errors in the console.
- Read your context and instructions
- Compiled the first run doctor
I have completed the environment detection and local check. The primary blocker is a version mismatch: the project requires Node >=20.11.0, but the local environment is pinned to 18.20.4 via .nvmrc.
First-Run Diagnostic Report
| Category | Item | Result | Evidence |
|---|---|---|---|
| Runtime | node | FAIL | Found v18.20.4; engines requires >=20.11.0 |
| Runtime | python3 | PASS | Found v3.11.2; matches requires-python |
| Env Var | STRIPE_KEY | PASS | Found in shell |
| Env Var | DATABASE_URL | FAIL | Declared in .env.example but missing in shell |
| Env Var | REDIS_PORT | WARN | Read in server.js but missing from .env.example |
| Commands | npm install | PASS | package.json found; npm binary available |
| Commands | db:migrate | WARN | Target exists in package.json; not run |
Onboarding Guide (Partial)
1. Prerequisites
- Node.js: [unverified — version mismatch] Install Node.js >=20.11.0. (Current: 18.20.4)
- Python: [verified: ran
python3 --version] 3.11.2
2. Environment
- Missing Keys:
DATABASE_URL(See.env.example) - Note: The doctor never reads or prints values. Ensure these are exported in your shell.
3. Troubleshooting
- FAIL:
nodeversion is too low. - Fix: Update Node.js to match the
enginesfield inpackage.jsonor update your version manager. - FAIL: Missing
DATABASE_URL. - Fix: Export the key or initialize your
.envfile.
Next steps
- Update Node.js to v20.11.0 or higher.
- Export the
DATABASE_URLenvironment variable. - Re-run
python3 scripts/onboard.py check .to verify the fixes.
Connects securely to your tools. The creator never sees your data.
About this skill
Onboarding guides rot the moment they are written. New teammates waste hours debugging "works on my machine" issues because documentation reflects a developer's environment from six months ago rather than the current repo state.
What it does
- Detects toolchains by scanning
package.json,.nvmrc,pyproject.toml,go.mod, and other version manifests to identify required runtimes. - Validates environments through a read-only probe of the local
PATH, comparing observed binary versions against declared minimums and pins. - Audits environment variables by cross-referencing keys in
.env.exampleagainst actual source code usage to find undocumented requirements. - Map setup commands by identifying installation scripts, database migrations, and build targets within
Makefilesorpackage.json. - Generates verified guides that label every single instruction as either
verified(it ran and passed) orunverifiedwith a specific reason.
How it works
- Run detection to identify the project's languages, managers, and container configurations based on existing repository files.
- Execute checks to produce a PASS/FAIL table of binaries, versions, and environment keys present on the current machine.
- Generate the guide to output a dated snapshot containing prerequisites, setup orders, and troubleshooting steps for failures.
Frameworks & tools
The tool is built with a standard-library-only Python script (onboard.py). It supports detection for Node.js, Python, Go, Rust, Docker, and Makefile-based projects.
Why this beats prompting it yourself
Generic prompts often hallucinate setup steps or blindly trust outdated README files. This skill enforces a strict read-only execution policy and marks its own limitations, ensuring a new hire never follows a "guess" disguised as a command.
Use cases
- Fixing stale READMEs by generating a fresh onboarding guide that reflects the actual code requirements.
- Debugging new hire failures by running a check on their machine to identify missing binaries or env keys.
- Pre-flight checks before demos or interviews to ensure a fresh clone boots correctly without tribal knowledge.
- Environment audits to find discrepancies between version manager pins and engine minimums.
Known limitations
The tool is strictly read-only and will not install packages, run migrations, or start services. It probes for environment key existence only and never reads or prints actual values.
Read-only: never installs or runs project code. Env checks verify key names only, not values. Limited to POSIX shells. Exit 1 indicates blockers, not overall project health.
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
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
2 uses
Times used to date
Free forever
No account required to browse
Trust & safety
Security scan
Security scan passed 1 month ago
- Free with an Agensi account
Requires