Skip to main content
Agent skill

Codebase Onboarding

Analyze an unfamiliar codebase and generate a structured onboarding guide with architecture map, key entry points, conventions, and a starter CLAUDE.md. Use when joining a new project or setting up Claude Code for the first time in a repo.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Codebase Onboarding when an AI agent needs a reusable SKILL.md workflow for this job: Analyze an unfamiliar codebase and generate a structured onboarding guide with architecture map, key entry points, conventions, and a starter CLAUDE.md. Use when joining a new project or setting up Claude Code for the first time in a repo.

When not to use it

Skip Codebase Onboarding when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/codebase-onboarding
# Save SKILL.md to ~/.claude/skills/codebase-onboarding/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/codebase-onboarding/SKILL.md. For a shared project, commit the folder at .claude/skills/codebase-onboarding/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Codebase Onboarding skill for this task: First time opening a project with Claude Code. Confirm any required inputs or files before making changes.

What supports this recommendation?

88/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
100/100
Practical detail
100/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Codebase Onboarding

Systematically analyze an unfamiliar codebase and produce a structured onboarding guide. Designed for developers joining a new project or setting up Claude Code in an existing repo for the first time.

## When to Use

- First time opening a project with Claude Code - Joining a new team or repository - User asks "help me understand this codebase" - User asks to generate a CLAUDE.md for a project - User says "onboard me" or "walk me through this repo"

## How It Works

### Phase 1: Reconnaissance

Gather raw signals about the project without reading every file. Run these checks in parallel:

``` 1. Package manifest detection → package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml, build.gradle, Gemfile, composer.json, mix.exs, pubspec.yaml

2. Framework fingerprinting → next.config.*, nuxt.config.*, angular.json, vite.config.*, django settings, flask app factory, fastapi main, rails config

3. Entry point identification → main.*, index.*, app.*, server.*, cmd/, src/main/

4. Directory structure snapshot → Top 2 levels of the directory tree, ignoring node_modules, vendor, .git, dist, build, __pycache__, .next

5. Config and tooling detection → .eslintrc*, .prettierrc*, tsconfig.json, Makefile, Dockerfile, docker-compose*, .github/workflows/, .env.example, CI configs

6. Test structure detection → tests/, test/, __tests__/, *_test.go, *.spec.ts, *.test.js, pytest.ini, jest.config.*, vitest.config.* ```

### Phase 2: Architecture Mapping

From the reconnaissance data, identify:

**Tech Stack** - Language(s) and version constraints - Framework(s) and major libraries - Database(s) and ORMs - Build tools and bundlers - CI/CD platform

**Architecture Pattern** - Monolith, monorepo, microservices, or serverless - Frontend/backend split or full-stack - API style: REST, GraphQL, gRPC, tRPC

**Key Directories** Map the top-level directories to their purpose:

<!-- Example for a React project — replace with detected directories --> ``` src/components/ → React UI components src/api/ → API route handlers src/lib/ → Shared utilities src/db/ → Database models and migrations tests/ → Test suites scripts/ → Build and deployment scripts ```

**Data Flow** Trace one request from entry to response: - Where does a request enter? (router, handler, controller) - How is it validated? (middleware, schemas, guards) - Where is business logic? (services, models, use cases) - How does it reach the database? (ORM, raw queries, repositories)

### Phase 3: Convention Detection

Identify patterns the codebase already follows:

**Naming Conventions** - File naming: kebab-case, camelCase, PascalCase, snake_case - Component/class naming patterns - Test file naming: `*.test.ts`, `*.spec.ts`, `*_test.go`

**Code Patterns** - Error handling style: try/catch, Result types, error codes - Dependency injection or direct imports - State management approach - Async patterns: callbacks, promises, async/await, channels

**Git Conventions** - Branch naming from recent branches - Commit message style from recent commits - PR workflow (squash, merge, rebase) - If the repo has no commits yet or only a shallow history (e.g. `git clone --depth 1`), skip this section and note "Git history unavailable or too shallow to detect conventions"

### Phase 4: Generate Onboarding Artifacts

Produce two outputs:

#### Output 1: Onboarding Guide

```markdown # Onboarding Guide: [Project Name]

## Overview [2-3 sentences: what this project does and who it serves]

## Tech Stack <!-- Example for a Next.js project — replace with detected stack --> | Layer | Technology | Version | |-------|-----------|---------| | Language | TypeScript | 5.x | | Framework | Next.js | 14.x | | Database | PostgreSQL | 16 | | ORM | Prisma | 5.x | | Testing | Jest + Playwright | - |

## Architecture [Diagram or description of how components connect]

## Key Entry Points <!-- Example for a Next.js project — replace with detected paths --> - **API routes**: `src/app/api/` — Next.js route handlers - **UI pages**: `src/app/(dashboard)/` — authenticated pages - **Database**: `prisma/schema.prisma` — data model source of truth - **Config**: `next.config.ts` — build and runtime config

## Directory Map [Top-level directory → purpose mapping]

## Request Lifecycle [Trace one API request from entry to response]

## Conventions - [File naming pattern] - [Error handling approach] - [Testing patterns] - [Git workflow]

## Common Tasks <!-- Example for a Node.js project — replace with detected commands --> - **Run dev server**: `npm run dev` - **Run tests**: `npm test` - **Run linter**: `npm run lint` - **Database migrations**: `npx prisma migrate dev` - **Build for production**: `npm run build`

## Where to Look <!-- Example for a Next.js project — replace with detected paths --> | I want to... | Look at... | |--------------|-----------| | Add an API endpoint | `src/app/api/` | | Add a UI page | `src/app/(dashboard)/` | | Add a database table | `prisma/schema.prisma` | | Add a test | `tests/` matching the source path | | Change build config | `next.config.ts` | ```

#### Output 2: Starter CLAUDE.md

Generate or update a project-specific CLAUDE.md based on detected conventions. If `CLAUDE.md` already exists, read it first and enhance it — preserve existing project-specific instructions and clearly call out what was added or changed.

```markdown # Project Instructions

## Tech Stack [Detected stack summary]

## Code Style - [Detected naming conventions] - [Detected patterns to follow]

## Testing - Run tests: `[detected test command]` - Test pattern: [detected test file convention] - Coverage: [if configured, the coverage command]

## Build & Run - Dev: `[detected dev command]` - Build: `[detected build command]` - Lint: `[detected lint command]`

## Project Structure [Key directory → purpose map]

## Conventions - [Commit style if detectable] - [PR workflow if detectable] - [Error handling patterns] ```

## Best Practices

1. **Don't read everything** — reconnaissance should use Glob and Grep, not Read on every file. Read selectively only for ambiguous signals. 2. **Verify, don't guess** — if a framework is detected from config but the actual code uses something different, trust the code. 3. **Respect existing CLAUDE.md** — if one already exists, enhance it rather than replacing it. Call out what's new vs existing. 4. **Stay concise** — the onboarding guide should be scannable in 2 minutes. Details belong in the code, not the guide. 5. **Flag unknowns** — if a convention can't be confidently detected, say so rather than guessing. "Could not determine test runner" is better than a wrong answer.

## Anti-Patterns to Avoid

- Generating a CLAUDE.md that's longer than 100 lines — keep it focused - Listing every dependency — highlight only the ones that shape how you write code - Describing obvious directory names — `src/` doesn't need an explanation - Copying the README — the onboarding guide adds structural insight the README lacks

## Examples

### Example 1: First time in a new repo **User**: "Onboard me to this codebase" **Action**: Run full 4-phase workflow → produce Onboarding Guide + Starter CLAUDE.md **Output**: Onboarding Guide printed directly to the conversation, plus a `CLAUDE.md` written to the project root

### Example 2: Generate CLAUDE.md for existing project **User**: "Generate a CLAUDE.md for this project" **Action**: Run Phases 1-3, skip Onboarding Guide, produce only CLAUDE.md **Output**: Project-specific `CLAUDE.md` with detected conventions

### Example 3: Enhance existing CLAUDE.md **User**: "Update the CLAUDE.md with current project conventions" **Action**: Read existing CLAUDE.md, run Phases 1-3, merge new findings **Output**: Updated `CLAUDE.md` with additions clearly marked

Intended uses

  • First time opening a project with Claude Code
  • Joining a new team or repository
  • User asks "help me understand this codebase"
  • User asks to generate a CLAUDE.md for a project
  • User says "onboard me" or "walk me through this repo"
  • Run dev server: npm run dev
  • Run tests: npm test
  • Run linter: npm run lint
  • Database migrations: npx prisma migrate dev
  • Build for production: npm run build

Implementation notes

  • Don't read everything — reconnaissance should use Glob and Grep, not Read on every file. Read selectively only for ambiguous signals.
  • Verify, don't guess — if a framework is detected from config but the actual code uses something different, trust the code.
  • Respect existing CLAUDE.md — if one already exists, enhance it rather than replacing it. Call out what's new vs existing.
  • Stay concise — the onboarding guide should be scannable in 2 minutes. Details belong in the code, not the guide.
  • Flag unknowns — if a convention can't be confidently detected, say so rather than guessing. "Could not determine test runner" is better than a wrong answer.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.