michaelschecht Codebase Onboarding
Use this skill when the goal is to explain a codebase clearly to a new teammate, contractor, or future maintainer.
When To Use
- Onboard a new engineer to an unfamiliar repo
- Refresh stale project documentation after major refactors
- Produce a service overview before handoff or open-sourcing
- Build a team wiki page or internal runbook from the code itself
Expected Outputs
- Architecture overview with major system boundaries and data flow
- Key file map showing what matters and why
- Local setup guide from clone to running tests
- Common task runbooks for recurring developer workflows
- Debugging guide with logs, common failures, and recovery steps
- Contribution guide with branch, PR, and validation expectations
Recommended Workflow
- Inspect package metadata, scripts, dependencies, and top-level directories.
- Identify core runtime paths, routes, jobs, schema files, and integration points.
- Review recent git history to understand active areas and major changes.
- Write docs for the intended audience: junior, senior, or contractor.
- Prefer actionable setup and debugging steps over abstract theory.
Quality Bar
- Keep setup instructions runnable on a fresh machine
- Explain the "why" behind important files, not just the path names
- Link to deeper docs instead of repeating them
- Update onboarding docs in the same change set as code when possible