# Repo Onboarder

> repo-onboarder

- Skill: `timdevai/repo-onboarder` (Agent Skill)
- Install (CLI): `npx skillmds@latest add timdevai/repo-onboarder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/timdevai/repo-onboarder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: timdevai (https://skillmd.com/u/timdevai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/timdevai/repo-onboarder

---

# repo-onboarder

> First time in a codebase? This skill gives you a 5-minute tour: entry points, key modules, conventions, and where to start reading.

## When to activate

Trigger phrases: `new repo`, `show me around`, `where do I start`, `tour this codebase`, `cold on this project`.

Activate automatically on the FIRST message in a new project directory if the user appears unfamiliar (asks where things are, what does X do).

## Process

1. Read top-level files: `README.md`, `package.json`/`pyproject.toml`/`Cargo.toml`/`go.mod`, `Makefile`, `docker-compose.yml`
2. Identify entry points (`main.py`, `index.ts`, `cmd/*/main.go`, `app.py`, etc.)
3. Map directory roles: `src/`, `tests/`, `docs/`, `scripts/`, `infra/`, `migrations/`
4. Detect conventions:
   - Test framework
   - Code style (formatter config, linter rules)
   - Commit style (from git log)
   - Branch naming (from `git branch -a`)
   - PR template (`.github/PULL_REQUEST_TEMPLATE.md`)
5. Surface the 5 most important files to read first
6. Emit a one-page tour

## Output format

```
Repo: <name>
Lang: <language> | Framework: <fw> | Tests: <framework>

Entry point(s):
- <path> — <one-line role>

Directory map:
- src/        <one-line>
- tests/      <one-line>
- ...

Conventions:
- Style: <e.g. black + ruff>
- Tests: <e.g. pytest, run with `make test`>
- Commits: <e.g. conventional>

Start reading here (in order):
1. <path>:<line> — <why>
2. <path>:<line> — <why>
3. <path>:<line> — <why>
4. <path>:<line> — <why>
5. <path>:<line> — <why>

How to run it locally:
<commands>

Where to add a new feature:
<pattern matching how features are added in recent commits>
```

## Inputs

- Project root path
- Recent git activity (what files changed recently = currently active areas)

## Outputs

- One-page tour (markdown)
- 5 numbered files to read with rationale

## Slash command

`/tour` — run on current directory.

## Anti-patterns prevented

- Reading every file before doing anything (wastes 1+ hour)
- Asking the user "what does this codebase do" when the README answers it
- Recommending paths that don't exist in this project

## Example

User: `/tour`
Skill (after scanning):
```
Repo: proteus
Lang: Python | Framework: stdlib + anthropic SDK | Tests: pytest

Entry point: proteus.py — boots event bus + orchestrator + agents

Directory map:
- agents/    domain handlers (memory, research, admin, content, code, trading)
- server/    BYOK API + scheduler + user store
- sources/   external event sources (file watcher today, gmail/cal planned)
- sync/      always-on daemon
- tests/     pytest suite

Conventions:
- Style: black + ruff (no config = defaults)
- Tests: pytest, run with `python -m pytest tests/`
- Commits: conventional commits (feat:, fix:, chore:)

Start here:
1. proteus.py:1 — see how the pieces wire together
2. agents/event_bus.py:1 — the async queue
3. agents/orchestrator.py:1 — routing logic
4. agents/tier0_filter.py:1 — local Ollama call
5. agents/memory_agent.py:1 — pattern for a domain agent

Run it: `python proteus.py`
Add a new agent: drop a module in agents/, register in proteus.py _register_agents()
```