onboard-repo
Skill0 starsChanged 3 months agoMITView on GitHub
Builds an accurate working model of an unfamiliar codebase from evidence rather than assumption, then writes or refreshes an AGENTS.md so later sessions and other agents start informed. Use when opening a repository for the first time, when the user asks how a codebase works, how to build or run it, where something lives, or asks to create, update or improve AGENTS.md, CLAUDE.md or contributor documentation.
6 other projects use a version of this.
Adopted by
Most recently taken up by
- tounsils/claude-code-skillstheir own version, first seen Oct 25, 2026
- raniellimontagna/agent-toolkittheir own version, first seen Oct 11, 2026
- YogirajA/Claude-Skillstheir own version, first seen Sep 17, 2026
- WaDadidou/skillstheir own version, first seen Sep 11, 2026
- n24q02m/better-code-review-graphtheir own version, first seen Mar 22, 2026
- n24q02m/crgtheir own version, first seen Mar 22, 2026
Other versions6 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 6
- n24q02m/better-code-review-graph★ 76same name
- n24q02m/crg★ 76same name
- raniellimontagna/agent-toolkit★ 3same name
- tounsils/claude-code-skills★ 1same name
- WaDadidou/skills★ 1same name
- YogirajA/Claude-Skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository4 other files it gives its agents.
- audit-test-doublesSkill
- qa-test-planSkill
- review-migrationSkill
- verify-changeSkill
The file
We split this skill into the rules it gives an agent
4 rules. 0 are common, 4 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 6 edited versions we read keep these.
4
Distinctive
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 45
Do not transcribe commands from a README.
- Distinctive: line 58
Read three or four files that do the same kind of thing and note what they share: layering, naming, error handling, how data access is …
- Distinctive: line 86
Write to the repository root.
- Distinctive: line 99
Leave out anything obvious from looking, anything already in the README, and anything you did not verify.
“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Onboard onto a repository
The failure mode when landing in unfamiliar code is not being unable to find things. It is forming a confident, wrong model early and then interpreting everything else through it.
Work from evidence, and record which parts are verified.
Procedure
1. Shape before detail
Establish size and structure before reading any implementation. Reading files at random in a large repository produces a model built from whatever you happened to open.
git log --oneline -1 && git log --since='90 days ago' --oneline | wc -l # is it alive?Find: the number of projects/packages, the entry points, the test projects, and the directories that hold most of the code. Note the top-level layout and what each part is for.
2. Read what the repository already says
In this order, because later sources are usually staler:
AGENTS.md,CLAUDE.md,.cursor/rules/,.github/copilot-instructions.mdREADME.md,CONTRIBUTING.mddocs/, architecture decision records- CI workflows — the most reliable source in the repository
CI is honest in a way documentation is not: it is executable, and it fails when it is wrong. The build, test and lint commands in CI are the real ones, whatever the README says.
3. Establish the commands, by running them
Do not transcribe commands from a README. Run them.
- build
- test
- lint / format
- run locally
Record what actually worked, including flags and prerequisites the docs omitted. If something failed, record that too — a documented command that does not work is a finding, and the next person hits it in ten minutes.
4. Find the conventions from the code
Read three or four files that do the same kind of thing and note what they share: layering, naming, error handling, how data access is done, how tests are structured, how features are registered.
Where the codebase is inconsistent, say which pattern is the current one — usually the one in the most recently changed files:
git log --since='60 days ago' --name-only --pretty=format: | sort | uniq -c | sort -rn | head -30The most-changed files are where the work happens, and they teach more than the oldest ones.
5. Find the rules that are enforced
Anything the repository enforces mechanically is a hard constraint, not a preference:
architecture tests, analyzers, TreatWarningsAsErrors, commit hooks, required checks.
These matter more than any written style guide, because they will stop your change.
6. Identify what you do not know
Explicitly list the parts you did not verify: areas you did not read, commands you could not run, claims from the docs you could not confirm. This list is the most useful part of the output — it stops the next reader treating a guess as established.
Writing AGENTS.md
Write to the repository root. If one exists, update it rather than replacing it — it may contain decisions you cannot re-derive.
Include only what a competent newcomer cannot work out in thirty seconds:
- what the project is, in two lines
- the layout, and what each part is for
- the exact build, test and run commands that you ran
- conventions that differ from the language's defaults
- mechanically enforced rules, and where they live
- known traps — the things that waste an afternoon
- what is out of bounds: generated directories, vendored code, legacy areas
Leave out anything obvious from looking, anything already in the README, and anything you did not verify. A guide that is half guesses is worse than none, because it is trusted.
Keep each file under 12,000 characters. Some agent tools impose exactly that limit on instruction files and truncate or reject beyond it — silently. In a large repository, prefer a short root file that points at per-area files over one long one.
Close with the date and what was verified:
<!-- Verified 2026-09-03: build, test and lint commands run clean. Deployment and the
reporting module were not exercised. -->Rules
- Never state a command you have not run. Mark it unverified instead.
- CI beats the README. Where they disagree, CI is what is true.
- Record the traps. The thing that cost you twenty minutes will cost everyone else twenty minutes.
- Say what you did not check. Confidence with no coverage is the failure this skill exists to prevent.
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.

