When to use this
- A new team member is joining and setup/orientation docs are thin or stale.
- Repeated Slack questions from new hires point at a documentation gap.
- Not a substitute for the README -- this is oriented at a person joining the team, covering things a README for external users wouldn't (team conventions, where to ask for help, common gotchas).
The skill file
Copy this verbatim. It's written in the SKILL.md format (YAML frontmatter + markdown instructions) that Claude Code, and increasingly other agent tools, read directly.
--- name: onboarding-guide-generator description: Write an onboarding guide for a new team member joining this specific codebase/team -- verified environment setup, codebase orientation (where things live and why), and team-specific conventions not covered by the README. Use when onboarding docs are missing or stale. --- # Onboarding Guide Generator Write for someone who has never seen this codebase. Verify every command against what's actually in the repo -- a broken first command destroys trust in the rest of the doc. ## Sections 1. **Environment setup**: exact, verified steps from a clean checkout to a running local environment, including tool versions and any local services (database, cache) needed. 2. **Codebase orientation**: not a full architecture doc -- a short map of "if you need to change X, look in Y," covering the 5-10 most common areas a new engineer touches early. 3. **How this team works**: branch naming, PR/review expectations, commit message convention, where decisions get discussed (if not obvious from the repo alone, note this is team-specific and may need a human to confirm/fill in). 4. **First good tasks**: if identifiable (good-first-issue labels, a known list), point at them. 5. **Common gotchas**: anything that reliably trips up newcomers -- a non-obvious required env var, a test that needs a specific local service running, a naming convention that isn't self-evident. ## Verify, don't assume Every setup command should be checked against the actual scripts/config in the repo, the same discipline as the README skill -- an onboarding guide with a broken step 1 is worse than no guide.
Installing it elsewhere
The frontmatter/body split above is Claude Code's convention. Here's how to carry the same instructions into other tools:
Save the file below verbatim (frontmatter included) at that path, project-local or in ~/.claude/skills/ for a user-level skill. Claude Code loads the name/description pair to decide when to pull it in, or you invoke it directly as /onboarding-guide-generator.
Convert the YAML frontmatter to Cursor's rule format (description, globs, alwaysApply: false) and keep the markdown body as the rule content. Cursor surfaces it by description match, same idea as Claude Code's auto-load.
Codex CLI (and increasingly other agentic CLIs) read AGENTS.md at the repo root as always-on instructions. Paste the markdown body under a heading like ## {title}; for GitHub Copilot's coding agent, the equivalent file is .github/copilot-instructions.md.
Append the markdown body to .windsurfrules at the repo root. Windsurf treats the whole file as always-on context, so keep only the instructions you want applied on every request.
- Copying setup steps from the README without adding the onboarding-specific context (why, common failure points) that makes them actually helpful.
- Writing team-process sections (review norms, communication channels) from assumption instead of flagging them as needing confirmation from a human.
- Letting the guide go stale the next time setup changes -- note it should be revisited alongside major tooling changes.