timdevai 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
- Read top-level files:
README.md,package.json/pyproject.toml/Cargo.toml/go.mod,Makefile,docker-compose.yml - Identify entry points (
main.py,index.ts,cmd/*/main.go,app.py, etc.) - Map directory roles:
src/,tests/,docs/,scripts/,infra/,migrations/ - 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)
- Surface the 5 most important files to read first
- 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()