Repo onboarding
Map an unfamiliar codebase before making changes: layout, entry points, conventions, hot spots.From its SKILL.md
npx -y skills add ayaqen/Agents-Scripts --skill repo-onboardingAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
1.8 KB, as published. Nobody here has run it
repo-onboarding
Build an accurate mental model of a codebase in minutes, before touching anything. Wrong assumptions made in the first five minutes cost hours later.
When to use
- First session in a repo you haven't worked in.
- Returning to a repo after significant time or a large refactor landed.
- Before estimating or planning any non-trivial change.
Workflow
- Run the mapper for a structural overview:
It prints layout, file census by language, entry points, and the files with the most recent churn (churn ≈ where the action is)../scripts/repo-map.sh /path/to/repo - Read docs before code, in this order:
README,AGENTS.md/CLAUDE.md,CONTRIBUTING, then anything indocs/whose front matter or title matches your task. - Find how the project proves itself: locate the test command (CI workflow files are the ground truth — read
.github/workflows/) and run it once before changing anything, so you know the baseline. - Trace one representative path end-to-end (a request, a CLI invocation, a build) and note the layering conventions you see: error handling style, DI patterns, naming.
- Write down three things: where your change goes, what pattern it should imitate, and which tests must stay green. Only then start editing.
Pitfalls
- Skipping the baseline test run — you'll later burn time bisecting a failure that was already there.
- Trusting the README's build instructions over CI's. CI is what actually runs; READMEs rot.
- Pattern-matching on the oldest code in the repo. Prefer imitating the most recently reviewed code (recent merged PRs) — that reflects current conventions.