Skip to content

skillWorkflow

Codebase Onboarding

Builds a written map of an unfamiliar repository: entry points, layers, conventions, the commands that work, plus the areas most likely to break.

npx workspacetemplates add codebase-onboarding --tool claude-code

Writes 1 file to .claude/skills/codebase-onboarding/

.claude/skills/codebase-onboarding/SKILL.md28 lines · 1.9 KBFile
---
name: codebase-onboarding
description: "Builds a written map of an unfamiliar repository: entry points, layers, conventions, the commands that work, plus the areas most likely to break."
---

# Codebase onboarding

Read, run and map. Change nothing in the repository.

## Steps

1. Identify the project: languages, frameworks, package manager and build tool from manifests and lockfiles. List top-level directories with one line on each.
2. Find how to run it: the README, `Makefile`, `package.json` scripts, `docker-compose.yml` and CI config. Try the install, build and test commands. Record exactly which worked and which failed, with the error.
3. Find entry points: `main`, server bootstrap, route tables, job and queue consumers, CLI commands, scheduled tasks. Trace one request or command from entry to storage and back, naming each file it passes through.
4. Describe the layers and the data model: the main entities, where they are defined, and where the database schema and migrations live. Note external services and the config or environment variables each needs.
5. Read conventions from the code itself: naming, error handling, logging, how tests are laid out, how dependencies are injected. Quote one example file for each.
6. Find the risky areas. Use `git log --since=1.year --name-only` to count the files that change most. Look for large files, deep nesting, clusters of unfinished-work comments, modules with no tests, and code that is imported everywhere.
7. Write the map in a file the user names, or print it if none is named, using these headings: Overview, Run it, Entry points, Layers, Data, Conventions, Risky areas, Open questions.

## Rules

- Every claim cites a path. Mark anything inferred as a guess.
- Do not install global tools or run anything that writes to databases or external services.
- Keep the map under 120 lines.

## Report

The map, the commands that worked, and the three files to read first.

What it does

The first day in a new repository is mostly spent guessing where things live. This skill has the agent explore it in a fixed order and write down what it finds, with file paths you can check, so you start from a map instead of a blank page.

The map separates facts it confirmed from guesses, and it points at the places most likely to hurt: tangled modules, thin test coverage and files that change in every incident.

Example

you › I just inherited this repo. Give me a map before I touch anything.

agent › Overview: Express and TypeScript API with a Postgres database and a BullMQ worker. Run it: npm ci and npm test pass; npm run dev fails without DATABASE_URL (see .env.example). Entry points: src/server.ts, src/worker.ts. Risky areas: src/billing/invoice.ts changed 41 times last year and has no test; src/utils/helpers.ts is imported by 63 files. Read first: src/server.ts, src/routes/index.ts, src/billing/invoice.ts.

Questions

Will it modify anything?
It only writes the map file if you name one. Installing and test commands run locally, and anything that touches shared services is skipped.
How does it find risky areas?
It combines commit churn, file size and missing tests. A file that changes constantly and has no coverage is flagged before a large file that never moves.
  • Bug Report Triage

    SkillWorkflow

    Free
  • Context Management

    SkillWorkflow

    Free
  • Library Selection

    SkillWorkflow

    Free