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 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?
mkdir -p ~/.claude/skills/codebase-onboarding # Save SKILL.md to ~/.claude/skills/codebase-onboarding/SKILL.md
- 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.
- 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.
- 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.
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.