From skills
Onboards newcomers to a codebase by walking curated reading lists or cold-starting from repo docs. Answers targeted subsystem questions like 'how does our auth flow work'.
How this skill is triggered — by the user, by Claude, or both
Slash command
/skills:onboard-our-stackThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Two jobs, one skill:
Two jobs, one skill:
Tell them apart from the request: a named subsystem -> targeted; "new", "onboard me", "where do I start", "understand the project" -> broad.
The institutional knowledge — which files are load-bearing, in what order, and
the gotchas that live only in people's heads — is curated in .onboard/topics.yaml
by a maintainer, ONCE, and committed. A newcomer just asks; they never author it
and never change code to make this skill work.
Pick the highest tier the repo supports. Never block the newcomer on setup, and never demand maintainer input from someone who came here to learn.
Curated config present (.onboard/topics.yaml at repo root) -> use it.
Best tier: real ordering, real gotchas. See Broad / Targeted below.
No config -> COLD START. Do NOT refuse, and do NOT drop into config authoring (that is a maintainer-only flow, below). Orient the newcomer from the repo's own authoritative sources, in this order if present: README.md, CLAUDE.md / AGENTS.md, ARCHITECTURE.md, docs/ (a product doc and a runbook if they exist), the dependency manifest (pyproject.toml / requirements.txt), and the entry point (main.py / app). Synthesize a grounded orientation, citing each file. Derive getting-started from README/RUNBOOK. Then say plainly: "This is auto-read from your repo's docs, not a curated walk — the tribal knowledge a teammate would warn you about (stale docs, landmines, why it's built this way) isn't captured yet. A maintainer can run the setup, or I can help one author it."
The line you must not cross: reading and citing the team's own docs is ALLOWED — that surfaces what's written, it is not a guess. Inventing gotchas, or asserting a file is load-bearing without evidence from a doc or the entry point's own imports, is NOT allowed. When unsure, attribute it or omit it.
No config and no docs -> minimal. Show the entry point, the dependency
manifest, and the top-level tree; say honestly there's little to go on, and
suggest a maintainer author .onboard/topics.yaml.
Walk onboarding_path in order — it is the curriculum the maintainer chose;
don't reorder it.
getting_started topic points at
(RUNBOOK/README) so the run/test commands stay current — do not hardcode or
guess them.request_lifecycle — narrate ONE request end to end across the
layers. This single story is what gives the model; everything else is depth.Pace it: offer to go one topic at a time rather than dumping all of them.
Match the question to one topic by key or one_liner. Read its read_in_order
in order; if a path is missing the config is stale — warn, name the file, read
the rest, flag the gap. Synthesize the mental model, surface that topic's
watch_out_for, cite files, point at the adrs/specs for the why. Orientation,
not a line-by-line walk. Offer the nearest adjacent topic next.
.onboard/topics.yaml has two top-level keys:
onboarding_path: ordered list of topic keys — the broad-mode curriculum.topics: map of <key> -> { one_liner, read_in_order, watch_out_for,
optional adrs }. Two topics are special by convention and belong early in the
path: getting_started (points at the run/test docs) and request_lifecycle
(the end-to-end story).See references/topics.example.yaml for the schema and a worked example.
A maintainer authors the config once, grounded in files they verify exist, and
commits it. Trigger the authoring flow ONLY when someone explicitly asks to set
up or curate onboarding — never as the default response to a missing config.
Run scripts/check_topics.py in CI so stale paths fail the build; a stale
reading list teaches a wrong model, the one failure this skill exists to prevent.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub osipchuk/agent-skills