Onboarding Docs skill for Claude Code

Onboarding docs work when a new engineer, without interrupting anyone, has a working environment on day one, merges a small real change in the first week, and can explain the system’s main request path by the end of week two. Measure that with each new hire and fix the docs where they stalled.

Ground rules

• Every command in the setup guide is run on a clean machine (or fresh container) before publishing, and again each time a new hire uses it.
• Write for someone smart who knows nothing about this company: expand every acronym, link every internal tool, never write “just”.
• Keep docs where the code is (repo docs/onboarding/) so they change in the same pull requests as the systems they describe; link out to the HR or IT checklist rather than copying it.
• Short and layered: a one-page start-here, then deeper pages. Nobody reads a 40-page wiki on day one.
• Each new hire owns fixing what was wrong for them, as their first pull request.

The doc set

Doc	Purpose	Length
START_HERE.md	Order of operations for week one, links to everything else	1 page
Access checklist	Accounts, groups, permissions, who approves, expected wait	Checklist
Setup guide	From blank laptop to tests passing and app running locally	As long as it needs, every step verified
Architecture tour	The system in one diagram, one request traced end to end, where code lives	2-4 pages
Glossary	Internal terms, service names, acronyms, customer jargon	Table
First tasks	A ladder of 3-5 real tasks increasing in scope	List with links
How we work	Branching, reviews, deploys, on-call, meetings, where decisions live	1-2 pages
People map	Who owns what, where to ask which kind of question	Table

Workflow

- [ ] 1. Interview the last 2-3 hires: where did they get stuck?
- [ ] 2. Inventory existing docs; mark stale, duplicate, missing
- [ ] 3. Write the access checklist and setup guide; verify on a clean machine
- [ ] 4. Write the architecture tour from the code, not from memory
- [ ] 5. Build the glossary and people map
- [ ] 6. Curate the first-task ladder
- [ ] 7. Write START_HERE and the 30/60/90 outline
- [ ] 8. Test with the next hire; fold their fixes back in

1-2. Find the real gaps

Ask recent hires: what took longest, what did you have to ask about, what was wrong in the docs, what do you wish you had known in week one. Search the team chat for repeated newcomer questions. These answers set the priorities, not a generic template.

3. Access checklist and setup guide

Access checklist format:

| Access | How to request | Approver | Typical wait | Needed for |
|---|---|---|---|---|
| GitHub org `acme` (team `payments`) | IT ticket, template "New engineer" | Eng manager | Same day | Everything |
| AWS `payments-dev` read-only | Request in access portal | Team lead | 1 day | Debugging staging |
| PagerDuty | Added by manager in week 3 | Manager | - | On-call shadowing |

Setup guide rules:

• State supported platforms and prerequisites with versions (OS, CPU architecture, tool versions) at the top.
• Prefer one bootstrap command (make setup, ./scripts/bootstrap, a dev container, or Nix/devbox) over 30 manual steps; document what it does.
• Every step: the command, what success looks like (expected output), and the fix for the most common failure.
• End with a verification step that proves everything works:

make test           # expect: all tests pass, about 2 minutes
make dev            # expect: app at http://localhost:3000, log in as [email protected] / see seed data

• Secrets: say exactly where they come from (secret manager path, .env.example plus a command), never paste them into docs.
• Verify by running the guide in a fresh VM or container and fixing every deviation. If that is impossible, mark the guide with the date and person who last verified it.

4. Architecture tour

Build it from the code (use codebase-onboarding to map the repository if needed):

1. One diagram: users, entry points, services, data stores, queues, third parties. Ten boxes or fewer; link deeper diagrams (see c4-diagrams or mermaid-diagrams).
2. Trace one representative request end to end with file paths: route handler -> service -> database -> queue -> worker -> notification. Real paths, e.g. api/src/routes/orders.ts:42.
3. Where things live: a table of top-level directories and what belongs in each.
4. The non-obvious: historical decisions that still constrain the code, known sharp edges, things that look wrong but are intentional (link ADRs).
5. How to observe it: where logs, dashboards, traces, and error tracking are.

5. Glossary and people map

Glossary entries are one line each and include terms that sound generic but have local meanings (“account” vs “workspace” vs “tenant”). Sort alphabetically; link to code or docs where the concept lives.

People map: area -> owning team -> channel -> who to ask for what (code review, production access, product questions). Use team names and channels rather than only individual names so it survives reorgs.

6. First-task ladder

Step	Example	Teaches
1. Docs fix	Fix whatever was wrong in onboarding docs	PR flow, review norms
2. Tiny code change	Copy change, small bug with a failing test	Build, test, deploy pipeline
3. Small feature	A contained endpoint or UI change behind a flag	Feature flags, code structure
4. Cross-service change	Touches two components or a migration	Architecture, coordination
5. On-call shadow	Shadow a shift, then handle one alert with backup	Operations

Label suitable issues in the tracker (good-first-issue, onboarding) and keep 5+ available. Pair each with a named buddy for review.

7. START_HERE and 30/60/90

START_HERE.md is a dated sequence:

## Day 1
- [ ] Access checklist items marked "Everything"
- [ ] Setup guide through `make test`
- [ ] Meet your buddy: <how assigned>
## Week 1
- [ ] Architecture tour, then trace a request yourself with the debugger
- [ ] Ship first-task ladder steps 1-2
## Weeks 2-4
- [ ] Steps 3-4; shadow on-call; read the last 3 postmortems

30/60/90 outline: expectations at 30 days (shipping small changes independently), 60 (owning a feature end to end), 90 (on-call rotation, reviewing others’ code). Managers adjust per role; the doc gives the default.

8. Test and maintain

• Each new hire keeps a friction log during week one and files a docs PR from it.
• Track time to first merged PR and time to working environment per hire; they should fall over time.
• Add a “last verified” date to the setup guide; re-verify when it is older than 90 days or after major tooling changes.
• Link-check docs in CI where possible (see docs-site).

Gotchas

• Wiki pages that duplicate repo docs drift apart; keep one source and link to it.
• Setup steps that only work on the author’s machine (globally installed tools, cached credentials, an old database dump) are the most common blocker.
• Architecture docs written from memory describe the system as intended, not as built. Verify paths and flows against the code.
• Do not bury security basics: secret handling, production access rules, and data handling belong in week one.
• An onboarding doc full of names goes stale at the first reorg; prefer team aliases.

Output contract

docs/onboarding/
  START_HERE.md        # week-one sequence, links
  access.md            # checklist table
  setup.md             # verified YYYY-MM-DD on <OS/arch> by <who>
  architecture.md      # diagram, request trace with file paths, directory map
  glossary.md
  first-tasks.md       # ladder with tracker links
  how-we-work.md
  people.md            # ownership and channels
Metrics: time to working env <h>, time to first merged PR <days>, per hire