Codebase Onboarding
Map how the existing repository works before proposing or making changes.
When to use
Use for first-time orientation or an unfamiliar subsystem. Use codebase-design
to design a change, systematic-debugging for a specific failure, and
session-handoff to resume unfinished work. An onboarding request normally
authorizes reading and explaining, not running setup or rewriting instructions.
Evidence-first workflow
- Read AGENTS.md, existing project instructions and README. Note the repository
root, branch and scope. Preserve applicable instructions when documentation
disagrees with observed code; report the discrepancy for resolution.
- Inspect source paths with
rg --files, excluding dependency/build/generated
trees. Read relevant manifests, lockfile/tool-version metadata, test config,
CI and entry points. Avoid credentials and real environment files; consult
sanitized examples only when needed. Do not recursively read the whole repo.
- Identify languages and framework evidence, workspace boundaries and data
stores. Distinguish a dependency's presence from actual use. In a monorepo,
state the working directory for each command and component.
- Trace one real request or job from entry through validation, business logic,
persistence/external boundary and result. Cite existing paths and line
numbers. If that trace is incomplete, mark the missing link; do not invent it.
- Derive conventions from a few representative files and test/CI configuration.
Inspect recent history only if available. For shallow/unborn repositories,
state that historical conventions cannot be established.
- Produce a concise map using the output template.
Mark commands as observed, executed, unavailable or unknown. Reading a
package script proves its definition, not that it succeeds. Flag stale README
commands rather than silently repeating them.
- Finish with the best starting locations for the user's task and concrete
unknowns. Suggest next checks whose side effects fit the requested scope.
Outputs and boundaries
Default to a conversation answer. Write a guide, AGENTS.md or CLAUDE.md only
when writing/updating that artifact is part of the user's task. Read existing
instructions first, merge relevant evidence and avoid conflicting duplicates.
Explicit authorization already given in the task does not need to be requested
again. Put any approved output in the target project, not this shared skill.
This is an instruction workflow; no scanner or generator script is advertised.
The probe guide describes how to evaluate it on isolated
repositories, including checks that read-only work leaves no diff.
Adapted from ECC codebase-onboarding.
The MIT notice is retained.
1---2name: codebase-onboarding3description: >-4 Explain an unfamiliar repository using evidenced architecture, entry points,5 request or job flow, test commands and conventions. Use for onboard me,6 understand this repo, where do I start, or preparing a codebase orientation.7license: MIT; see LICENSE.txt8metadata:9 source: https://skillmd.com/skills/hongyime/codebase-onboarding10 author: Local setup11 version: "1.0.0"12 platform: "Codex, Antigravity (agy), OpenCode, Muse on Windows, macOS, Linux (Debian)"13---1415# Codebase Onboarding1617Map how the existing repository works before proposing or making changes.1819## When to use2021Use for first-time orientation or an unfamiliar subsystem. Use `codebase-design`22to design a change, `systematic-debugging` for a specific failure, and23`session-handoff` to resume unfinished work. An onboarding request normally24authorizes reading and explaining, not running setup or rewriting instructions.2526## Evidence-first workflow27281. Read AGENTS.md, existing project instructions and README. Note the repository29 root, branch and scope. Preserve applicable instructions when documentation30 disagrees with observed code; report the discrepancy for resolution.312. Inspect source paths with `rg --files`, excluding dependency/build/generated32 trees. Read relevant manifests, lockfile/tool-version metadata, test config,33 CI and entry points. Avoid credentials and real environment files; consult34 sanitized examples only when needed. Do not recursively read the whole repo.353. Identify languages and framework evidence, workspace boundaries and data36 stores. Distinguish a dependency's presence from actual use. In a monorepo,37 state the working directory for each command and component.384. Trace one real request or job from entry through validation, business logic,39 persistence/external boundary and result. Cite existing paths and line40 numbers. If that trace is incomplete, mark the missing link; do not invent it.415. Derive conventions from a few representative files and test/CI configuration.42 Inspect recent history only if available. For shallow/unborn repositories,43 state that historical conventions cannot be established.446. Produce a concise map using the [output template](templates/orientation.md).45 Mark commands as observed, executed, unavailable or unknown. Reading a46 package script proves its definition, not that it succeeds. Flag stale README47 commands rather than silently repeating them.487. Finish with the best starting locations for the user's task and concrete49 unknowns. Suggest next checks whose side effects fit the requested scope.5051## Outputs and boundaries5253Default to a conversation answer. Write a guide, AGENTS.md or CLAUDE.md only54when writing/updating that artifact is part of the user's task. Read existing55instructions first, merge relevant evidence and avoid conflicting duplicates.56Explicit authorization already given in the task does not need to be requested57again. Put any approved output in the target project, not this shared skill.5859This is an instruction workflow; no scanner or generator script is advertised.60The [probe guide](references/probes.md) describes how to evaluate it on isolated61repositories, including checks that read-only work leaves no diff.6263Adapted from [ECC codebase-onboarding](https://github.com/affaan-m/ECC/blob/e482e579415fde18357cafce70f177ae19fd7f03/skills/codebase-onboarding/SKILL.md).64The [MIT notice](LICENSE.txt) is retained.