Codebase Onboarding
Skill0 starsChanged 4 months agoMITView on GitHub
Systematic principal-engineer onboarding into any unknown repository. Auto-load when asked to "understand this codebase", "get up to speed", "explore this repo", "how does this project work", "map the structure", or before making the first change in an unfamiliar repository. Covers discovery order (README → build config → entry points → tests → CI → git history), what to read first, how to map module structure, and how to distinguish deliberate convention from historical accident. Repo-agnostic: works for Python, Node, Rust, monorepos.
- Reads credentials
- Deletes or force-pushes
- Installs packages
In this repository25 other files it gives its agents.
- Agent EngineeringSkill
- API and Interface DesignSkill
- Architecture AnalysisSkill
- Build and ReleaseSkill
- Campaign PlanningSkill
- Change ControlSkill
- Code Review PlaybookSkill
- Configuration ManagementSkill
- Debugging PlaybookSkill
- Dependency ManagementSkill
- Documentation PracticesSkill
- Engineering MinimalismSkill
- Evaluation FrameworksSkill
- Failure ArchaeologySkill
- LLM Integration ReliabilitySkill
- LLM System DesignSkill
- Observability and DiagnosticsSkill
- Performance EngineeringSkill
- Prompt and Context EngineeringSkill
- Proof and AnalysisSkill
- Refactoring PlaybookSkill
- Research MethodologySkill
- Security Review PlaybookSkill
- System DesignSkill
- Validation And TestingSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 28
Read in this order. Each step answers one question.
- Distinctive: line 77
All repo-agnostic; run from the repo root.
- Distinctive: line 155
Likely to drift: commit counts and hashes as repos grow.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Codebase Onboarding
Purpose
Turn an unknown repository into a working mental model in minutes, not hours, by reading artifacts in a fixed high-signal order instead of wandering. The output is a map: what the project does, how it builds and runs, where the entry points are, what is tested, and which patterns are deliberate convention versus accident.
When to Use / When NOT to Use
Use when:
- You are about to make your first change in a repository you have not read.
- Asked to summarize, audit, or evaluate an unfamiliar project.
- A task references files or modules you cannot yet place in the system.
- Resuming work on a repo after long enough that your model may be stale.
Do NOT use when:
- You need to understand why the code is the way it is (past incidents, reverts, hardening arcs) → load failure-archaeology.
- You need to judge module boundaries, error taxonomies, or data flow in depth → load architecture-analysis.
- You are hunting a specific bug, not building a map → load debugging-playbook.
- The question is only about dependencies or lockfiles → load dependency-management.
Core Methodology
Read in this order. Each step answers one question; stop reading a file once the question is answered.
- README — What does this claim to be? Note install command, run command, and any threat model or design-doctrine statements. A written threat model in a README is a load-bearing document, not marketing.
- Build/package config (
pyproject.toml,package.json,Cargo.toml,pnpm-workspace.yaml) — What language/version, what dependencies (count them — few is a signal of deliberate minimalism, many is a signal of accretion), what scripts/entry points are declared, is it a workspace/monorepo? - Environment surface (
.env.example, config module) — Every env var is an external coupling: services, secrets, tunables. This is the fastest inventory of what the system talks to. - Entry points — The
[project.scripts]/bin/maindeclared in step 2. Read the entry file top to bottom; it shows startup order and the module dependency direction. - Tests — What is tested reveals what the authors fear. Note test-to-code ratio and where tests concentrate. A repo with only security tests made a risk decision; record it, don't judge it yet.
- CI config (
.github/workflows/,.gitlab-ci.yml) — What is enforced vs. merely documented. Absence of CI means every README claim is unverified by machinery — trust build/test commands only after running them. - Git history, first and last 10 commits —
git log --oneline | headand| tail. First commits show the intended skeleton; recent commits show current concerns. Full mining is failure-archaeology's job; here you only want the arc. - Directory map — Now, and only now, list the tree. With steps 1–7 done, every directory should be nameable in one sentence. Any directory you cannot explain is your next read.
Decision tree: where to start reading
Is there a README?
├─ yes → read it first; does it name a run command?
│ ├─ yes → find that command's target in build config → that file is the entry point
│ └─ no → build config scripts/bin section is your entry-point index
└─ no → build config → declared entry points → largest source file in the
top-level package → tests (they demonstrate intended usage)
Is it a workspace/monorepo (pnpm-workspace.yaml, cargo workspace, packages/)?
├─ yes → onboard the leaf package the task touches FIRST, root config second;
│ note cross-package version/publish coupling explicitly
└─ no → proceed linearly through steps 1–8Convention vs. accident
A pattern is convention (imitate it) if at least two of these hold; otherwise treat it as accident (do not propagate) until proven:
- It appears in 3+ files or in every instance of its situation.
- It is named in README, comments, or a commit message.
- A test enforces it.
- It survived a refactor (visible in git history).
Example conventions worth spotting: frozen dataclasses everywhere = immutability doctrine; custom exception classes with actionable messages = deliberate error UX; zero TODO/FIXME markers = the authors finish or delete, so don't introduce TODOs.
Onboarding checklist
- Can state the project's purpose in one sentence without the README open.
- Know the exact install, run, and test commands (and have run the test command if permitted).
- Can list every env var / external service the system touches.
- Can name the entry point file and the module dependency direction.
- Know where tests concentrate and what is deliberately untested.
- Know whether CI exists and what it enforces (possibly: nothing).
- Have listed 3 conventions to imitate and any accidents to avoid.
- Every top-level directory explained in one sentence.
Discovery Commands
All repo-agnostic; run from the repo root.
# Steps 1-2: identity and build surface
ls -a
cat README.md
cat pyproject.toml package.json Cargo.toml 2>/dev/null # whichever exists
# Step 3: environment surface
cat .env.example 2>/dev/null
grep -rn "os.environ\|getenv" --include="*.py" . # Python
grep -rn "process.env" --include="*.ts" --include="*.js" . # Node
# Step 4: entry points
grep -n "scripts" pyproject.toml 2>/dev/null
grep -n '"bin"\|"main"\|"scripts"' package.json 2>/dev/null
# Step 5: tests
find . -path ./node_modules -prune -o -name "*test*" -print
# run them ONLY after the trust gate below: pytest tests/ | npm test | cargo test
# Step 6: CI
ls .github/workflows/ 2>/dev/null || echo "no GitHub CI"
# Step 7: history arc
git log --oneline | head -10
git log --oneline | tail -5
git log --oneline | wc -l
# Step 8: map + size
find . -path ./node_modules -prune -o -path ./.git -prune -o -type f \( -name "*.py" -o -name "*.ts" -o -name "*.rs" \) -print | xargs wc -l | sort -n
# Convention detection
grep -rn "frozen=True" --include="*.py" .
grep -rn "TODO\|FIXME" --include="*.py" --include="*.ts" . | wc -lTrust gate — before running ANY command that executes repo-controlled code (npm install / npm test run postinstall hooks and arbitrary scripts; pip install -e . executes setup code; pytest imports conftest.py): confirm the repository's provenance is trusted, read package.json "scripts" / setup.py / conftest.py first, or run in a sandbox. Reading files is always safe; executing the repo is not.
Ecosystem variants: pip install -e . / npm install / pnpm install / cargo build for the build step; monorepos may need pnpm -r <cmd> or cargo build --workspace.
Failure Modes & Anti-patterns
| Symptom | Mistake | Correction |
| Hours spent, no map | Reading files alphabetically or by directory order | Follow the fixed discovery order; each artifact answers one question |
| Confident but wrong run instructions | Trusting README with no CI verifying it | No CI = unverified claims; execute install/test commands before repeating them |
| New code clashes with house style | Skipped convention detection, imported personal defaults | Grep for repeated patterns first; imitate what appears 3+ times |
| "This repo has no error handling" | Judging by absence of your favorite pattern | Find the repo's own pattern (custom exceptions, observation strings) before declaring a gap |
| Missing half the system | Onboarding only the package the task names in a monorepo | Check for workspace files first; map package coupling before editing |
| Treating a hack as gospel | Copying a one-off workaround into new code | One occurrence + no test + no doc = accident; verify before propagating |
| "Untested = careless" | Assuming missing tests are an oversight | Tests may be concentrated on the highest-risk surface by choice; check what IS tested |
Repository Examples
PRISM (~/prism, as of 2026-07-04). Python 3.10+ FastAPI AI code reviewer for GitHub PRs using local Ollama. The full discovery order runs in ~5 minutes: README → pyproject.toml (install pip install -e ., run prism) → .env.example inventories the entire external surface (GITHUB_TOKEN, GITHUB_WEBHOOK_SECRET, OLLAMA_HOST default http://localhost:11434, OLLAMA_MODEL default llama3.2, MAX_FILES_PER_PR=10, MAX_LINES_PER_CHUNK=120) → five modules (prism/config.py, diff.py, github.py, reviewer.py, server.py) → tests are a single file, tests/test_security.py, run with pytest tests/ — a deliberate decision to test only the highest-risk surface → no CI → git log --oneline shows a 4-commit arc: e264a72 initial → b7bbabb README env-var reference → 51b92c9 security hardening → b011239 security tests. Conventions passing the test above: frozen dataclasses (Settings, Hunk, FileDiff, Chunk, InlineComment) with a get_settings() singleton, and zero TODO/FIXME markers.
AGENTIX (~/agentix, as of 2026-07-04). ~700-line local agent framework on Ollama; hatchling build, pip install -e ".[dev]", pytest. README states the threat model explicitly: "the security boundary is you and the model you point it at, not the code" — reading that sentence first reframes every security judgment about the code (e.g. the shell blocklist ["rm -rf /", "sudo", "mkfs"] is documented as a guardrail, NOT a boundary). Prerequisites live outside the package manager: ollama pull llama3.2 and ollama pull nomic-embed-text — README-only setup steps a build-config-first reader would miss. Tests (tests/test_agent.py, test_memory.py, test_tools.py) use only monkeypatch + tmp_path: a minimal-tooling convention to imitate.
RAGIT (~/ragit, as of 2026-07-04). Local RAG CLI (typer): python3 -m pip install -e .; commands models/index/chat/clear; files ragit/cli.py, indexer.py, llm.py, retriever.py. Zero tests and zero CI — combined with tight pins (chromadb>=0.4.0,<0.5.0, numpy<2.0) this tells the onboarder that the pins are the repo's regression defense and must not be "cleaned up". Runtime state lives at ~/.ragit/<sha256-prefix>/: an example of why grepping for home-directory paths belongs in onboarding.
RUFLO (~/ruflo, as of 2026-07-04). pnpm monorepo publishing three synchronized npm packages (@claude-flow/cli, the claude-flow umbrella, and the ruflo alias) at identical versions. Onboarding a single package here without reading the workspace root misses the version-sync and dist-tag coupling; internal docs mark the ruflo dist-tag "EASY TO FORGET".
Validation Criteria
You applied this skill correctly if:
- You can answer, without re-opening files: purpose, run command, test command, env-var list, entry point, test concentration, CI status.
- Your first change matched existing conventions with no style corrections needed.
- You correctly predicted where a named feature lives before opening the file (spot-check yourself twice).
- You flagged at least one deliberate absence (no CI, no tests, no TODO markers) as a decision rather than a defect.
- Total onboarding time for a <2k-line repo was under 15 minutes.
Provenance & Maintenance
- Sources: prism, agentix, ragit, orphy, NYTW, asver, ruflo at
~/<repo>, investigated 2026-07-04. Prism's commit history independently re-verified viagit -C ~/prism log --onelineon 2026-07-04; other repo facts from the same-day investigation fact pack. - Doctrine encoded: these repos are deliberately local-first (local Ollama, no cloud LLM), minimal-dependency, zero-CI, with security proportional to a written threat model. The methodology treats such absences as decisions to detect, not defects to fix.
- Assumptions: repos remain at the listed paths; standard git/grep/find available. Anything beyond the fact pack is marked "(hypothesis — requires verification)".
- Re-verification commands:
git -C ~/prism log --oneline;cat ~/prism/.env.example;ls ~/agentix/tests;grep -n "chromadb\|numpy" ~/ragit/pyproject.toml. - Likely to drift: commit counts and hashes as repos grow; env-var defaults; ruflo package list and versions; the "zero CI anywhere" claim (any repo may add CI).
- Maintenance checklist: quarterly — re-run the re-verification commands; update example hashes/paths; confirm cross-referenced skills (failure-archaeology, architecture-analysis, debugging-playbook, dependency-management) still exist under
~/.claude/skills/; delete any example whose repo no longer matches.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

