Skip to content
Skills Library
Programming · Analysis

onboard-codebase

/onboard-codebase

Map an unfamiliar repository from the files actually read (what it is, entry points, how to run and test it, conventions, risks) and propose lines for the project memory. Use it when starting in a project new to you, when asked to explain or map a codebase, or while its memory is empty.

Repository
yaap ↗
Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Map an unfamiliar repository from the files actually read (what it is, entry points, how to run and test it, conventions, risks) and propose lines for the project memory. Use it when starting in a project new to you, when asked to explain or map a codebase, or while its memory is empty.

Original author description

Map an unfamiliar repository from the files actually read (what it is, entry points, how to run and test it, conventions, risks) and propose lines for the project memory. Use it when starting in a project new to you, when asked to explain or map a codebase, or while its memory is empty.

How it works

  1. Ground rules
  2. 1. Inventory
  3. 2. Entry points and paths
  4. 3. Run and test
  5. 4. Conventions
  6. 5. Risks
  7. 6. Propose memory lines
  8. Output
Original SKILL.md headings · 109 lines, 840 words
SKILL.md preview
---
name: onboard-codebase
description: Map an unfamiliar repository from the files actually read (what it is, entry points, how to run and test
  it, conventions, risks) and propose lines for the project memory. Use it when starting in a project new to you, when
  asked to explain or map a codebase, or while its memory is empty.
license: MIT
metadata:
  sources: agency-agents/engineering/engineering-codebase-onboarding-engineer.md, own
---

# Onboard a codebase

A wrong picture of a project causes more bad changes than any lack of skill. Build the picture from files you have
read, say which ones those were, and keep what lasts in the project memory so the next conversation starts from it.

## Ground rules

- **Only state what you read.** Every claim points to a file. "Requests are routed in `src/api/router.ts`" is a fact;
  "probably uses a service layer" is a guess, and a guess in an onboarding map gets repeated as truth.
- **Say what you did not read.** A map of one subsystem is not a map of the repository. List the folders you skipped.
- **Describe, do not review.** Onboarding is not the moment for refactoring ideas. Risks are noted as facts (no tests
  in `billing/`), not as plans.
- **Read only.** Change no files while onboarding, apart from the memory lines the user accepts at the end.

## 1. Inventory

Start from the repository map YAAP gives at the top of a project conversation (unless *Repository map* is switched
off in the Context settings); it shows folders, modules and public names, but check it against the files before
relying on it. Then read, in this order:

1. `README`, `CONTRIBUTING`, `AGENTS.md` or similar instructions, and `docs/` indexes.
2. Manifests and lockfiles (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`): language, framework,
   scripts, dependencies.
3. Build, CI and deployment files (`Makefile`, `Dockerfile`, `.github/workflows/`, `compose` files): how it is really
   built and tested, which often differs from the README.
4. Tool configuration (linters, formatters, type checkers, test runners): the conventions that are enforced.

Decide what kind of repository it is: an application, a library, a service, a monorepo with several of these, or a
mix.

## 2. Entry points and paths

Find the smallest set of files where the system starts: `main` functions, the server start, the router, CLI
commands, workers and scheduled jobs, or a library's public exports. Then trace one or two real paths end to end,
for example one request from the route to the database and back. Name each file on the way. A traced path teaches
more than a list of folders.

For a large repository, when `delegate` is available (in a project conversation), hand each area to an exploring
worker (it only reads) and ask for files, lines and a conclusion. Your own context stays small, and the workers'
reports are evidence you can cite. Without `delegate`, map the areas one at a time yourself.

## 3. Run and test

Find the commands for install, build, run and test in the scripts, the CI file and the README. Where the project
allows it, run the test command once and note the result: a suite that is already red, slow or needs a service is
the most useful thing a newcomer can learn. Running commands asks for approval; if the user declines, list the
commands as found, not as verified.

For a web app, start it with `start_process` with its port and look at it in the preview beside the chat.

## 4. Conventions

Write down what the code and its configuration show: naming, layout of a feature, how errors are handled, how tests
are named and where they live, the commit style (`git log`), the formatter and line length. Prefer conventions that
are enforced (a lint rule, a CI check) over ones you infer from two files, and say which is which.

## 5. Risks

Note, as facts with their file: areas without tests, generated code that must not be edited by hand, very large
modules, duplicated helpers, misleading names, configuration that holds or expects secrets, dependencies that are far
behind, and anything the README says that the code contradicts.

## 6. Propose memory lines

The project memory (`.blueprint/memory.md`) is seen by every conversation in the project. Propose a few short lines
for its sections (*Decisions*, *Conventions*, *Lessons learned*, *Notes*): facts that will matter in later work and
are not obvious from the repository map. Good: "Tests run with `uv run pytest` from `backend/`; the e2e suite needs
the dev server on port 5173." Not useful: "The project uses Python."

Show the lines and ask which to keep. Write only the accepted ones, one `update_memory` call each.

## Output

```
# <project name>

<One sentence: what this codebase is.>

## In five minutes
- Kind: <application / library / service / monorepo>, <languages and frameworks>
- Entry points: `<path>` (<why it matters>), ...
- A traced path: `<entry>` -> `<handler>` -> `<logic>` -> `<storage or output>`
- Read these three files first: `<path>`, `<path>`, `<path>`

## Structure
| Path | What it holds |
|---|---|
| `<path>` | <purpose> |

## Run and test
- Build: `<command>` (<verified / found in <file>>)
- Run: `<command>`
- Test: `<command>` (<result if run>)

## Conventions
- <convention> (<enforced by <tool> / seen in <files>>)

## Risks
- <fact> (`<path>`)

## Proposed memory lines
- <Section>: <line>

## Read / not read
- Read: <files and folders>
- Not read: <folders skipped>
```

Versions

The database has no other skills named onboard-codebase.

Database snapshot: 13.11.2026 · package version 61ea38a10111 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100codebase-onboarding
    Maps an unfamiliar repository before changing it - stack, build/test/run commands, entry points, data flow, conventions and how changes ship - and writes a short map. Use when starting work in a repo you have not seen, when asked to explain how a codebase works, onboard to a…
  • 90explain-codebase
    Onboard to an unfamiliar codebase by mapping its architecture, entry points, and data flow. Use when starting work in a new or unknown repository and you need a navigable mental model fast.
  • 90repo-onboarding
    Use when starting in an unfamiliar repository, new codebase, greenfield checkout, or 'where do I start' moment and you need a fast structured map of stack, entrypoints, patterns, risks, and next steps before any edits. Triggers: onboard me to this repo, map the codebase, explore unfamiliar project.
  • 100codebase-onboard
    Quickly map and explain an unfamiliar JavaScript/TypeScript or Python codebase — architecture, entry points, data flow, how to run it, and where to make a given change. Use whenever the user opens a new project, asks "explain this repo", "gimana struktur project ini", "where is…
  • 100codebase-onboarding
    Map an unfamiliar repository into an onboarding guide (stack, architecture, entry points, conventions, commands) and a starter or refreshed agent instructions file (AGENTS.md or CLAUDE.md). Use when joining a project, asked to explain a codebase, or to create or refresh that file.
  • 100workflow-onboard
    First-contact orientation for an unfamiliar codebase. Use when "I'm new to this repo", "orient me", "explain this codebase", "what does this do?", "onboard me", "first day on this project", or "catch me up on the codebase".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.