version: "1.0.2" name: codebase-onboarding description: Use when entering a new codebase, needing a fast architecture map, or generating onboarding notes from an unfamiliar project. Focuses on reconnaissance first, then targeted reads. Describes the repo for navigation only; to judge architecture, dependency risk or docs drift, use review-health.

Codebase Onboarding

Use this skill for fast orientation in a new repository.

Workflow

1. Reconnaissance first:

• inspect top-level structure
• detect language, framework, package manager, tests, CI, env files

1. Identify:

• entry points
• key directories
• request/data flow
• project conventions

1. Read only the files that matter for those findings.
2. Emit the result according to the contract in the "Bootstrap" section below.

Output Shape

• Stack
• Architecture
• Key directories
• Common commands
• Conventions
• Gotchas

Rules

• Do not read everything.
• Prefer rg, manifests, config files, and a few representative files.
• Optimize for navigation and execution, not encyclopedic coverage.

Bootstrap (--bootstrap)

Map the recon results to the right files per the D-rules:

"Current status" belongs in the existing task plan's Handoff section, or in chat for small work (D0/D4). Do not create a separate status document or require a tracker.

Rules when generating:

• NEVER overwrite an existing file. Already exists → skip it and report "already exists". Fixing an old file to comply with D1/D6 is separate manual work, NOT part of bootstrap.
• Behavior claims in AGENTS.md MUST be markdown links relative to the file containing the link (D6). In docs/internals/*.md, links out to code → start with ../../; no label needed.
• docs/internals/overview.md keeps only what "a maintainer would get wrong without it": decisions + rationale, cross-module constraints, traps. No file catalogs, no control-flow retelling (D9).
• Do not make things up. Cannot verify → write unknown.
• When done, run bash ~/.claude/scripts/docs-compliance.sh <repo> and bash ~/.claude/scripts/docs-anchors.sh <repo>, and paste the output.

Permissions

Bootstrap authorizes creating the missing files above without overwriting existing ones. Routine documentation needs no separate approval; unclear requirements and material decisions follow D10. Staging and committing follow the task's authorization.