1
# Repo Onboarding
2
3
Maps an unfamiliar codebase into a working mental model: architecture summary,
4
entrypoints, directory guide, conventions, and verified run/test instructions. Writes
5
the result to `ONBOARDING.md` in the repo root so the next person (or agent session)
6
doesn't have to redo the exploration.
7
8
## When to use
9
10
- First thing when picking up a codebase you (or the agent) haven't worked in before.
11
- After joining a new project, to produce a document for the team rather than keeping
12
  the mental model only in your own head.
13
- Before a large refactor, to confirm your understanding of entrypoints and
14
  conventions matches reality.
15
16
## Install
17
18
```bash
19
npx openagents-cli add openagents/repo-onboarding
20
```
21
22
| Runtime | Installed to |
23
|---|---|
24
| `claude-code` | `.claude/skills/repo-onboarding/` |
25
| `cursor` | `.cursor/rules/repo-onboarding/` |
26
| `codex` | `.codex/skills/repo-onboarding/` |
27
| `openai-agents` | `.openai-agents/repo-onboarding/` |
28
| `generic` | `.openagents/repo-onboarding/` |
29
30
## Inputs
31
32
| name | type | required | default | description |
33
|---|---|---|---|---|
34
| `root_dir` | path | no | `.` | Root directory of the repository to map |
35
| `depth` | string | no | `standard` | `quick` (structure only), `standard` (+ entrypoints/conventions), or `deep` (+ actually runs install/test) |
36
37
## Example run
38
39
```
40
> Onboard me to this repo. Standard depth is fine.
41
```
42
43
The agent reads `README.md`/manifest/CI config, maps the directory structure, finds
44
entrypoints (HTTP routes, CLI `main`, exported library API), extracts naming and
45
testing conventions, determines the real install/run/test commands, and writes
46
`ONBOARDING.md`.
47
48
## Files
49
50
- `WORKFLOW.md` — the step-by-step procedure (entry point).
51
52
## Limitations
53
54
- `deep` depth executes install/test commands; only use it in an environment where
55
  that's safe (e.g. a disposable container or clean checkout), and expect it to take
56
  longer.
57
- Best on single-project repos and typical monorepos; unusual/non-standard build
58
  systems may need manual correction of the generated commands.
59
- Does not overwrite an existing `ONBOARDING.md` silently — it shows a diff and asks
60
  first, since a hand-maintained doc may carry context the pass can't infer.
61