onboarding-copilot

A Claude Code Skill that turns any codebase into a tailored onboarding brief: an architecture map, a ranked read-first file list, evidence-backed gotchas, and scoped good-first-tasks — the five-minute "here's how this repo works" conversation a senior engineer would give a new hire, generated from actually reading the code.

The problem

New-engineer ramp time is a real cost every eng org tracks, and the fix is usually either a stale onboarding doc nobody updates, or an hour of a senior engineer's time repeating the same orientation tour for the third time this quarter. Neither scales, and both go stale the moment the codebase does. What a new hire actually needs isn't more documentation — it's a specific, checkable answer to "what do I read first, what will trip me up, and what's a safe first thing to fix."

What it does

1. You point Claude at a repo — yours, a teammate's, or someone else's public repo entirely. No other input is required; the codebase itself is the raw material, unlike the planning tools in this pipeline that consume another tool's JSON output.
2. Following the rubric in skill/SKILL.md, Claude actually explores the repo — entry points, high-fan-in modules, git history, tests — and maps the architecture, ranks a read-first list against specific signals (not "this file is important"), surfaces gotchas that each carry a checkable evidence pointer, and scopes good-first-tasks traceable back to something real (a TODO, a docs gap, a rough edge found while mapping the repo).
3. That judgment is written to one onboarding.json file.
4. A small deterministic script, skill/scripts/render_outputs.py, validates it (every severity/size value is a real enum, every gotcha has evidence, every read-first entry has a priority) and renders:
   • onboarding.md — the full brief
   • onboarding_brief.md — a condensed version for a welcome Slack message or the top of a PR description
   • onboarding.html — the same brief as a single self-contained, styled page

Same split as the rest of the portfolio: the model does the judgment call, plain code does the formatting, so re-rendering after editing onboarding.json is instant and the brief can't drift out of sync with the analysis behind it.

Demo

Three worked examples, chosen for contrast — each onboarding.json was produced by actually reading the target repo (cloning the two external ones, reading real source, grepping for real evidence), not fabricated from a description:

• examples/critical-path-mapper/ — this portfolio's own critical-path-mapper, a small, single-file repo. Real gotcha found: its cycle-detection check lives in a different function than the rest of its input validation, so a caller trusting the validation function's name alone would miss it.
• examples/flask/ — pallets/flask. Real gotcha found: the Flask class you instantiate defines fewer methods (38) than its own base class (43) — most of what Flask actually does lives in a sansio/ package most users never open.
• examples/claude-cookbooks/ — anthropics/claude-cookbooks. Real gotcha found: every link in the README's recipe table (25 of them) still points at the repo's pre-rename name, and the repo's own link-checker config can't catch it — its accept list treats GitHub's redirect as success.

Live demo: punit-labs.github.io/onboarding-copilot — the rendered onboarding.html for the flask example above.

Using it

1. Copy skill/ into your Claude Code skills directory (project-level: .claude/skills/onboarding-copilot/, or user-level: ~/.claude/skills/onboarding-copilot/).
2. In Claude Code, from inside (or pointed at) any repo: "onboard me to this repo" / "write an onboarding brief for this codebase" / "what should a new engineer read first here."
3. Claude explores the repo and writes onboarding.json, then runs render_outputs.py to produce the brief.
4. Send onboarding_brief.md in a welcome message, or onboarding.md / onboarding.html when someone wants the full picture — architecture, every gotcha with its evidence, and the good-first-task list.

Requires only Python 3 (stdlib only, no dependencies) for the render step.

Design notes

• Every gotcha needs evidence a reader can check, same bar as exec-status-report's RAG ratings. "Be careful with side effects" isn't a gotcha; "3 of the last 8 commits to this file were bug fixes for the same off-by-one" is. SKILL.md says to reject a draft gotcha that would still be true of almost any codebase.
• Good-first-tasks are traceable, not invented. Each one names its source — a TODO comment, a docs gap, a rough edge found while mapping the architecture — so a reader can see it came from something real in the repo, not a generic suggestion.
• This is the one tool in the portfolio with no upstream JSON to consume. The other four tools chain into each other's outputs; this one's raw material is the codebase itself, which is also what makes it demoable against any public repo, not just this portfolio's own worked example.
• The renderer validates what the model can't guarantee. render_outputs.py rejects any onboarding.json with an invalid severity/size value or a read-first entry missing a priority, so a malformed brief fails loudly instead of shipping with a blank field where a reason should be.

License

MIT — see LICENSE.