</> Skill: generate a developer setup guide from your codebase

Every project has a setup process, and it’s almost never written down completely. The README says “run npm install” but forgets to mention the three environment variables you need, the local database, and the fact that Node 18 doesn’t work. This skill scans your project for setup requirements, reads your existing docs, and generates a step-by-step checklist a new developer can follow from zero to running the project on their machine.

The non-obvious thing this skill does well: it treats configuration files as the source of truth and the README as supplementary. Most onboarding docs are written from memory by someone who set up the project a year ago. This skill regenerates them from the actual files in the repo, so what new hires see matches what’s actually there.

The skill file

Copy the following into .claude/skills/onboarding-checklist.md. This is the complete skill definition.

# Onboarding checklist generator

## Purpose

Generate a personalized onboarding checklist for a new developer joining this project. Scan the codebase for setup requirements, read existing documentation, and produce a step-by-step guide from "clone the repo" to "run the project locally."

### Returns

A markdown checklist document with these sections, in this order:

- A header: project name, generation date, and a "review against README" caveat
- Prerequisites: tools and exact versions to install
- Get the code: clone command(s) and branch checkout
- Set up environment variables: required + optional, categorized
- Install dependencies: the exact install command for the project's package manager
- Set up the database: engine, startup, migrations, seed (each with a real command)
- Run the project: dev-server command and the URL to open
- Verify everything works: load check + test command
- Editor setup (optional): recommended extensions
- Next steps: links to CONTRIBUTING.md and other team docs

Plus structured metadata for downstream skills: the list of detected tools with versions, the env variable categorization, the package manager (npm / pnpm / yarn / pip / cargo / etc.), whether a devcontainer is present, and the sources used. A composing skill (such as a doc generator or a CI provisioner) can read these fields without parsing the markdown.

## When to use

- The user asks to create an onboarding guide
- The user asks "how do I set up this project?"
- A new team member needs to get started
- The user asks to document the setup process

## When not to use

- A maintained `ONBOARDING.md` already exists. The skill would silently overwrite it. Read it first and ask the user before regenerating.
- The project is a monorepo where setup varies per package or workspace. The skill assumes one project root. For monorepos, run it per-package and combine, or hand off.
- The setup requires platform-specific instructions the codebase can't reveal (corporate VPN, SSO, hardware drivers, license keys). The skill will produce a checklist with gaps the user has to fill.
- You don't have read access to the project's config files. Without them the checklist is guesswork.

## Steps

### 0. Confirm the project root and check for an existing guide

Before scanning, confirm the working directory is the project root. Run `git rev-parse --show-toplevel` if it's a git repo, or ask the user for the path otherwise. If `ONBOARDING.md` (or equivalent) already exists, read it first and tell the user what's in it. Ask whether to regenerate from scratch or annotate the existing file.

### 1. Scan for project configuration files

Check for the following files and record which ones exist. If a project has hundreds of nested config files (large monorepo), sample the top-level and most-recently-modified files first and note that you sampled rather than read everything; don't blow your context window on every `package.json` in `node_modules/`.

Package managers and dependencies:

- `package.json` (Node.js, check `engines` field for version requirements)
- `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile` (Python)
- `Cargo.toml` (Rust)
- `go.mod` (Go, check the go version directive)
- `Gemfile` (Ruby)
- `composer.json` (PHP)
- `pom.xml`, `build.gradle` (Java)

Environment and configuration:

- `.env.example`, `.env.sample`, `.env.template`
- `.envrc` (direnv)
- `.tool-versions` (asdf)
- `.node-version`, `.nvmrc`, `.python-version`, `.ruby-version`

Containers and infrastructure:

- `Dockerfile`, `docker-compose.yml`, `docker-compose.yaml`
- `.devcontainer/` directory (VS Code devcontainer)
- `Vagrantfile`
- `Makefile` (check for `setup`, `install`, `dev` targets)
- `justfile` (the `just` command runner, common in Rust projects)

Databases and services:

- `docker-compose.yml` (check for postgres, mysql, redis, mongo, etc.)
- `prisma/schema.prisma` (Prisma ORM, needs database)
- `migrations/` or `db/migrate/` (database migrations exist)
- `alembic/` or `alembic.ini` (Python database migrations)

CI and tooling:

- `.github/workflows/`, `.forgejo/workflows/`, `.gitlab-ci.yml` (CI config)
- `.pre-commit-config.yaml` (pre-commit hooks)
- `.husky/` (git hooks)
- `.editorconfig`
- `.vscode/extensions.json`

For each file found, read its contents. Cap reads at a reasonable budget (around 50 files for a normal repo, fewer for a monorepo) and note when you've capped.

### 2. Read existing documentation

Check for and read these files:

- `README.md` or `README`
- `CONTRIBUTING.md`
- `DEVELOPMENT.md` or `docs/development.md`
- `SETUP.md` or `docs/setup.md`
- `docs/getting-started.md`

Extract setup instructions that already exist. The onboarding checklist shouldn't contradict them. If existing docs are incomplete (they usually are), the checklist fills in the gaps.

### 3. Identify required tools and versions

From the files scanned in step 1, compile a list of tools the developer needs:

| Source file                           | Tool                    | Version            |
| ------------------------------------- | ----------------------- | ------------------ |
| `.nvmrc` or `package.json` engines    | Node.js                 | (specific version) |
| `.python-version` or `pyproject.toml` | Python                  | (specific version) |
| `go.mod`                              | Go                      | (specific version) |
| `Cargo.toml`                          | Rust/Cargo              | (edition year)     |
| `docker-compose.yml`                  | Docker + Docker Compose | (any)              |
| `.pre-commit-config.yaml`             | pre-commit              | (any)              |

For each tool, note the exact version required (if specified), how to install it (prefer version managers like nvm, pyenv, rustup over system installs), and whether it's strictly required or optional.

### 4. Identify environment variables

If `.env.example` (or similar) exists, read it and categorize each variable:

- Required, no default: variables the developer must fill in (API keys, database URLs, secrets)
- Required, has a sensible default: variables with example values that work for local development
- Optional: variables not needed for basic local development

If no env example file exists, check the source code for references to `process.env`, `os.environ`, `std::env`, or similar patterns. List any environment variables the code reads.

Sensitive content check: if a value in `.env.example` looks like a real credential (a long random string, not a placeholder like `your-api-key-here` or `xxx`), flag it to the user. Do not reproduce it in the generated output. Real values committed to `.env.example` is a common mistake worth surfacing.

### 5. Identify database setup steps

If the project uses a database:

1. Which database engine is required? Check `docker-compose.yml`, connection strings in env files, ORM config.
2. How to start it locally (Docker, local install, or cloud-hosted).
3. How to run migrations. For Prisma, default to `prisma migrate deploy` for first-time onboarding (it applies existing migrations without prompting). `prisma migrate dev` is for active development and prompts interactively, which an agent cannot drive. For Alembic, `alembic upgrade head`. For Django, `python manage.py migrate`.
4. How to seed development data (check for seed files, fixtures, or seed scripts).

### 6. Identify the dev server command

Check for the command to start the development server:

- `package.json` scripts: `dev`, `start`, `serve`
- `Makefile`: `dev`, `run`, `serve` targets
- `Procfile` or `Procfile.dev`
- `docker-compose.yml`: the main application service
- Instructions in README

Also note the port. Don't hardcode `localhost:3000` in the generated checklist if you can determine the actual port from the project config. For developers in remote environments, devcontainers, or cloud IDEs (Codespaces, Gitpod), `localhost` is the wrong address; mention this caveat in the generated guide so the user knows to substitute their forwarded URL.

### 7. Generate the checklist

Produce the onboarding checklist as a markdown document with these sections, in this order:

- Header with project name, generation date, and a brief "review against README" note
- Prerequisites: a checkbox list of tools to install, each with name, version, and install command
- Get the code: clone command and branch checkout. Use `git remote get-url $(git remote | head -1)` to detect the remote name (don't hardcode `origin`); fall back to a placeholder if no remote is configured.
- Set up environment variables: copy the example file, fill in required values, optional values noted
- Install dependencies: exact install command for the detected package manager
- Set up the database: start, migrate, seed, each as a copy-pasteable command
- Run the project: dev-server command and the URL to open
- Verify everything works: homepage check + test command
- Editor setup (optional): recommended extensions
- Next steps: links to CONTRIBUTING.md or other relevant docs

Every command must be copy-pasteable. Do not write "install the database" without a specific command. Do not write "set up your environment" without listing the exact variables. Pin a generation date and the latest commit SHA so the user can tell when the checklist is stale.

### 8. Present and ask (human action)

Show the complete checklist and tell the user which files you scanned to build it. Ask if they want you to write it to `ONBOARDING.md`, append to the README, or edit anything. Don't write to any file without explicit approval.

## Important rules

- NEVER guess at commands. If you can't tell how to start the dev server, mark it `[TODO: verify this command]` and tell the user.
- NEVER include real secrets or credentials in the checklist. Use placeholders.
- NEVER overwrite an existing `ONBOARDING.md` without confirming.
- Every command must be tested mentally against the project structure. If the project uses pnpm, do not write `npm install`.
- If the project has a devcontainer, mention it as an alternative fast path: "If you use VS Code or Codespaces, open this project in a devcontainer and skip most of the prerequisites."
- If the project has a Makefile or justfile with a `setup` target, mention it as a shortcut, but still document the manual steps for developers who want to understand each piece.
- Sensitive content scan: before showing the checklist, look for credential-shaped strings in any included content and replace with `[REDACTED]`.

How to install it

Create the skill file in your project:

mkdir -p .claude/skills
# paste the skill content into this file
touch .claude/skills/onboarding-checklist.md

For a personal skill that works across all your projects, place it in ~/.claude/skills/onboarding-checklist.md instead.

Example usage

A new developer joins your team and needs to get set up. Before:

README: "Run npm install and start the dev server. Database setup
        is in the Confluence doc someone wrote in 2023."

After running the skill:

> Generate an onboarding checklist for this project

Confirming project root: /workspaces/acme-app (git repo).
No existing ONBOARDING.md found.

Scanning project files (sampled 38 of 41 candidates)...
  Found: package.json, docker-compose.yml, .env.example,
  prisma/schema.prisma, .nvmrc, .pre-commit-config.yaml,
  .devcontainer/devcontainer.json

Reading existing docs...
  README.md exists but has no setup section.
  No CONTRIBUTING.md found.

Analyzing requirements...
  Node.js 22 (from .nvmrc)
  Docker + Docker Compose (PostgreSQL 16, Redis 7)
  12 environment variables (4 required, 3 have defaults, 5 optional)
  14 Prisma migrations
  Dev server: npm run dev on port 3000
  Devcontainer present at .devcontainer/devcontainer.json

# Onboarding checklist: acme-app

Generated on 2026-05-12 from commit a3f291b. Review against the
project README for any recent changes.

> Tip: this project has a devcontainer. If you use VS Code or
> Codespaces, open the repo in the devcontainer and skip most of
> the prerequisites below.

## Prerequisites

- [ ] Node.js v22: `nvm install 22`
- [ ] Docker + Docker Compose: https://docs.docker.com/get-docker/
- [ ] pre-commit: `pip install pre-commit`

## Get the code

- [ ] Clone the repository:
      git clone https://github.com/acme/acme-app.git
      cd acme-app

## Set up environment variables

- [ ] Copy the example env file:
      cp .env.example .env
- [ ] Fill in required values:
  - DATABASE_URL: use postgresql://postgres:postgres@localhost:5432/acme
  - REDIS_URL: use redis://localhost:6379
  - AUTH_SECRET: generate with openssl rand -base64 32
  - STRIPE_API_KEY: get a test key from the Stripe dashboard

## Install dependencies

- [ ] Install packages:
      npm ci

## Set up the database

- [ ] Start PostgreSQL and Redis:
      docker compose up -d
- [ ] Run existing migrations (use migrate deploy for onboarding,
      not migrate dev which prompts interactively):
      npx prisma migrate deploy
- [ ] (Optional) Seed data:
      npx prisma db seed

## Run the project

- [ ] Start the dev server:
      npm run dev
- [ ] Open http://localhost:3000 in your browser
      (if you're in a remote dev environment, use your forwarded URL)

## Verify everything works

- [ ] The homepage loads without errors
- [ ] Run tests: npm test
- [ ] All tests pass

---

Built from these files:
- package.json (Node 22, npm)
- docker-compose.yml (PostgreSQL 16, Redis 7)
- .env.example (12 variables, 4 required)
- prisma/schema.prisma (14 migrations)
- .devcontainer/devcontainer.json

Want me to write this to ONBOARDING.md or add it to the README?

How it works

The non-obvious choice in this skill is which document is treated as the source of truth. Configuration files win, every time. The README might say “run npm install” while the project actually uses pnpm; the lockfile knows the truth and the skill reads it. A prisma/schema.prisma file means you need a Postgres database whether or not the README mentions one. Treating the existing docs as supplementary, not authoritative, is what makes this skill useful for projects whose docs are out of date (which is most projects after about six months).

A few smaller decisions. Step 4’s three-bucket env-var categorization saves new developers from chasing optional integrations. Telling someone they don’t need to configure Sentry locally is a 10-minute time save and a confidence boost. Step 5 splits database setup into engine, startup, migration, and seed instead of “set up the database”; this is the section where most onboarding docs collapse into hand-waving. Step 7 detects the package manager from the lockfile (package-lock.json vs pnpm-lock.yaml vs yarn.lock) so the install command is right on the first try, not after the new hire installs the wrong one and then debugs the lockfile diff.

For more on the design principle of keeping skill output concrete and copy-pasteable, see skill design principles. The “ask before writing to a file” pattern in step 8 follows human-in-the-loop approval gates. If you also need API documentation generated for the same project, the doc generator skill is the natural companion, and agents for DevOps covers where this skill fits next to deployment automation.

Customizing it

If your team uses specific tools (a VPN, a password manager for secrets, a Slack channel to join), add a “Team setup” section to step 7 with items like “Request access to the staging environment from your team lead” or “Join the #acme-app channel in Slack.”

If your project has common setup gotchas, add a “Common issues” section at the end of the checklist template with items like “If port 3000 is already in use, check for other running dev servers with lsof -i :3000.” Maintaining this list as a team is more useful than rediscovering each footgun.

To target a specific OS, add a preference in step 3: “When suggesting install commands, use Homebrew on macOS, apt on Debian/Ubuntu, and direct downloads otherwise.” The skill normally produces platform-agnostic commands.

For multi-project repos, run the skill per-package and produce one checklist per workspace. The skill assumes one project root; trying to encode all paths in a monorepo into a single document is rarely worth the complexity.

To regenerate periodically, add a CI job that runs the skill and opens a PR if the generated output diverges from the committed ONBOARDING.md. That keeps the document fresh without anyone having to remember.

The point of all this

Most projects have onboarding documentation in the wrong place: someone’s head, an outdated wiki, or a Slack message from 2023. The fix is to make the docs a function of the codebase, not a separate artifact someone has to remember to update. Configuration files change with the code; the onboarding guide should change with the configuration. Run this skill when a new hire starts. Run it again every quarter. Don’t trust the README.