/skill

Codebase Onboarding

Credit

This skill was created by ECC. It is shared under a permissive open-source license. Keep this credit when you copy or change the skill.

When to Use

Use this skill when:

• Claude Code opens a project for the first time.
• A user joins a new team or repo.
• A user asks, "Help me understand this codebase."
• A user asks for a project CLAUDE.md.
• A user says, "Onboard me" or "Explain this repo."

Goal

Learn the project without reading every file. Find the main parts, show how they work together, and write a short guide that helps a new person begin.

Do not change project files unless the user asks. Do not run code that can post, deploy, delete data, or change live systems.

Step 1: Check Existing Rules

Before reading the code:

1. Find CLAUDE.md, AGENTS.md, CONTRIBUTING.md, and README files.
2. Read the rules that apply to the current folder.
3. Check for nested rule files in key folders.
4. Follow project rules even if they differ from this skill.

If a good CLAUDE.md already exists, review it. Do not replace it without need. Suggest small fixes instead.

Step 2: Scan the Project

Gather useful facts without opening every file. Run safe checks at the same time when possible.

Find package files

Look for files such as:

• package.json
• go.mod
• Cargo.toml
• pyproject.toml
• requirements.txt
• Gemfile
• pom.xml
• build.gradle
• composer.json

Read lock files only when you need an exact tool or package version.

Find tools and frameworks

Look for files such as:

• next.config.*
• nuxt.config.*
• angular.json
• vite.config.*
• tsconfig.json
• Dockerfile
• docker-compose.*
• .eslintrc*
• eslint.config.*
• .prettierrc*
• Makefile
• CI files under .github/workflows/

Do not name a framework from a file name alone. Check the package file or source code too.

Find entry points

Look for common entry files:

• main.*
• index.*
• app.*
• server.*
• CLI command files
• Web route files
• Worker or job files
• Mobile app start files

A repo may have more than one entry point. List each one and say what starts it.

View the folder shape

Show the top two folder levels first. Skip large or made files such as:

• .git/
• node_modules/
• vendor/
• build output
• cache folders
• coverage reports
• large data files

Open deeper folders only when they hold key code.

Find tests

Look for:

• tests/
• test/
• __tests__/
• *.test.*
• *.spec.*
• test tool config files

Find how tests are run. Do not run slow tests unless the user asks or the cost is clear.

Step 3: Map the Code

Find the main parts and how data moves between them.

For each main part, state:

• Its job
• Its folder
• What calls it
• What it calls
• What data it reads or writes

Trace at least one common path from start to end. For example:

HTTP request -> route -> service -> database -> response

If the repo has more than one app, make a small map for each app. Then show any shared code.

Do not guess. Mark facts that are not clear as Needs review.

Step 4: Find Project Rules

Read a few normal source files from each main area. Find rules for:

• File and folder names
• Function and class names
• Import paths
• Error handling
• Logs
• Settings and environment values
• Tests
• Comments and docs
• Code format

Separate written rules from patterns you only saw in code:

• Stated rule: Found in a rule or config file.
• Seen pattern: Found in several source files.
• Needs review: Seen once or not fully clear.

Do not copy secrets. List environment variable names only. Never show their values.

Step 5: Handle Special Cases

• Empty repo: Say what is present and give a short setup list.
• Very large repo: Start with root files and active apps. Ask which app matters most if the scope is still too wide.
• Many apps: List each app, its start file, and shared parts.
• Old code: Note old and new patterns. Do not call one the main rule without proof.
• Made code: Mark generated files and do not use them to infer style.
• Missing docs: Say which facts came from code.
• Broken setup: Report the exact missing file, tool, or step. Do not hide the error.
• Unknown language: Use package files, start scripts, and folder names to guide the scan.
• No tests: State that no tests were found. Do not claim the project has no test plan.
• Dirty worktree: Do not remove or replace the user's changes.

Output

Give the user these sections:

Project Summary

Explain what the project does in three to six short lines.

Project Map

Show the main folders and their jobs.

Entry Points

List each app, server, CLI, worker, or job entry point. Include the command that starts it when known.

Main Flow

Show one or more common paths through the code.

Tools and Commands

List confirmed commands for setup, start, test, lint, format, and build. Say Not found when a command is unknown.

Code Rules

List stated rules, seen patterns, and points that need review.

Risks and Open Questions

List missing docs, unclear code paths, old parts, unsafe scripts, or setup gaps.

Starter CLAUDE.md

Draft a short CLAUDE.md with:

• Project purpose
• Main folders
• Safe setup commands
• Test and check commands
• Code rules
• Files that should not be changed
• Known risks
• Any project-specific safety rules

Show the draft first. Write it to the repo only if the user asked for a file change.

Example

User request:

Onboard me to this repo and draft a CLAUDE.md.

Example result:

## Project Summary

This is a small web app for tracking tasks. The browser app sends requests to a Node.js API. The API stores tasks in PostgreSQL.

## Project Map

- `src/web/`: Browser pages and UI parts
- `src/api/`: HTTP routes and request checks
- `src/services/`: Main task rules
- `src/db/`: Database access
- `tests/`: Unit and API tests

## Entry Points

- `src/server.ts`: Starts the API with `npm run dev`
- `src/web/main.tsx`: Starts the browser app
- `src/jobs/cleanup.ts`: Removes old task logs

## Main Flow

Create task request -> API route -> task service -> database -> JSON response

## Tools and Commands

- Install: `npm install`
- Start: `npm run dev`
- Test: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`

## Code Rules

- Stated rule: Use TypeScript strict mode.
- Seen pattern: Service files end with `.service.ts`.
- Needs review: Some old routes return errors in a different shape.

## Risks and Open Questions

- The cleanup job has no test.
- The needed Node.js version is not written in the repo.

Quality Check

Before you finish, confirm that:

• Each claim points to a file or clear code path.
• All key entry points are listed.
• Commands come from project files, not guesses.
• Generated and third-party files were skipped.
• No secret values were shown.
• Unknown facts are marked clearly.
• No project file was changed without the user's request.