Onboarding a new developer with skills instead of a wiki
A new starter learns a codebase's conventions by getting them wrong. Skills in the repo mean their first pull requests already follow them.
Most onboarding is learning the unwritten rules: how state is handled here, where files go, what the review bot will complain about. New starters learn them one rejected pull request at a time.
Start from review comments
Look at the last month of review comments on new people's pull requests. The rules that keep coming up are the first skill. Write them as checkable rules, not advice.
Put them in the repo
Skills in .claude/skills/ come with the clone, so nothing needs installing, as in sharing skills with a team. Keep the why in a short doc linked from CLAUDE.md, and keep CLAUDE.md itself short: when CLAUDE.md gets too long.
Questions
Can skills replace onboarding docs?
Not entirely. People still need the why. Skills make the how automatic, so the conventions show up in their work from day one.
Which conventions are worth a skill first?
The ones reviewers correct most often in new people's pull requests. Those are the rules that are not obvious from the code.
Do new developers need to install anything?
Not if the skills live in the repository. Cloning the repo is enough.