Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Codebase onboarding orchestrator that scans, documents, summarizes, and teaches a codebase to new developers or to the AI agent itself.
layer
orchestrator
category
orchestration
triggers
["/onboard","onboard me to this codebase","explain this codebase","walk me through this project","learn this codebase","what does this project do"]
inputs
["Codebase path or repository","Optional focus area (specific module, feature, or layer)","Optional audience level (junior, senior, architect)","Optional output format (interactive walkthrough, written guide, diagram-heavy)"]
outputs
["Project overview and architecture summary","Module-by-module breakdown with key files","Data flow and dependency diagrams","Key patterns and conventions guide","Entry points and critical paths map","Onboarding guide document"]
["Reads all source files (read-only)","May generate documentation files (if requested)","May generate diagram files (if requested)","Writes comprehensive codebase knowledge to memory for future sessions"]
Onboard
Purpose
Onboard is the codebase learning and teaching orchestrator. It systematically explores a codebase and produces a comprehensive understanding that it can either present to a human developer or internalize for its own future use. Onboard answers the question every new team member asks: "How does this all fit together?"
Onboard goes beyond just listing files and directories. It traces data flows, identifies architectural patterns, maps dependencies, finds the critical paths, and explains the "why" behind design decisions when evidence is available. It produces both high-level summaries for quick orientation and deep-dive documentation for reference.
Workflow
Phase 1: Scan
Invoke scout -- Perform a comprehensive codebase scan:
Directory structure and organization pattern
File types and language composition
Entry points (main files, route files, index files)
Identify the tech stack -- Catalog all technologies:
Languages and versions
Frameworks and libraries (with versions)
Database and storage technologies
Infrastructure and deployment tools
Development tools (linters, formatters, test runners)
Invoke research (if needed) -- For unfamiliar frameworks or libraries, look up their purpose and patterns via Context7 to understand what role they play.
Phase 2: Map Architecture
Identify architectural pattern -- Determine the overall architecture:
Monolith vs microservices vs monorepo
MVC, layered, hexagonal, event-driven, etc.
Client-server, serverless, edge, etc.
Map module boundaries -- Identify logical modules and their responsibilities:
What each top-level directory represents
How modules communicate (imports, APIs, events, shared state)
Module ownership and dependency direction
Invoke mermaid -- Generate architecture diagrams:
High-level system architecture
Module dependency graph
Data flow diagrams for key operations
Database entity relationship diagram (if schema is accessible)
Trace critical paths -- Identify and document the most important code paths:
User authentication flow
Primary data creation/update flow
Request lifecycle (from entry to response)
Error handling flow
Background job processing (if applicable)
Phase 3: Analyze Patterns & Conventions
Extract coding conventions -- Document the patterns the codebase follows:
Complete multi-section document as described in Phase 4.
Architecture Deep Dive (for architects)
Focused on architectural decisions, trade-offs, and technical debt with supporting diagrams.
Decision Points
Condition
Action
Small project (< 50 files)
Quick summary format, skip deep architecture
Large project (> 500 files)
Full onboarding with all sections
Monorepo
Document each package/app separately, then integration
User asks about specific area
Focus onboard on that area, brief overview of rest
Unfamiliar technology detected
Invoke research via Context7 before documenting
Complex architecture
Invoke sequential-thinking to explain design rationale
Codebase already scanned in memory
Skip Phase 1, update only changed areas
Usage
Use Onboard when encountering a new codebase for the first time, when a new team member joins, or when you need to refresh understanding of a project you haven't worked on recently.
Best for:
First encounter with a new codebase
Onboarding new team members
Documenting an undocumented project
Refreshing context after time away from a project
Understanding a project before an audit
Preparing to contribute to an open-source project
Not ideal for:
Building features (use cook after onboarding)
Code review (use code-review)
Auditing for issues (use audit)
Examples
Example 1: Full codebase onboarding
User: /onboard Walk me through this codebase
Onboard workflow:
1. scout -> Scan: Next.js app, 234 files, TypeScript, Prisma, Tailwind
2. Architecture -> App Router pattern, API routes, Prisma data layer
3. mermaid -> System diagram, module deps, auth flow, data creation flow
4. Patterns -> Feature-based directories, custom hooks pattern, Zod validation
5. Document -> Full 6-section onboarding guide
6. Present -> Deliver guide, offer to deep-dive on any section
Example 2: Focused module onboarding
User: /onboard Explain the payment system in this codebase
Onboard workflow:
1. scout -> Focus scan on payment-related files and dependencies
2. Architecture -> Payment module boundaries, Stripe integration points
3. mermaid -> Payment flow diagram (checkout -> webhook -> fulfillment)
4. Patterns -> Payment-specific error handling, retry logic, idempotency
5. Document -> Payment system deep-dive document
6. Present -> Walkthrough of the payment flow with key files
Example 3: Self-onboarding (AI learning)
User: /onboard Learn this codebase so you can help me effectively
Onboard workflow:
1. scout -> Full codebase scan
2. Architecture -> Map all modules and patterns
3. Key abstractions -> Identify core utilities, shared types, conventions
4. Memory write -> Store complete codebase map, conventions, and patterns
5. Present -> Brief summary to user, deep knowledge stored for future use
6. Ready -> "I've learned the codebase. Here's a quick overview..."
Example 4: Open-source contribution prep
User: /onboard I want to contribute to this open-source project, help me understand it
Onboard workflow:
1. scout -> Scan codebase + look for CONTRIBUTING.md, CODE_OF_CONDUCT.md
2. Architecture -> Map the project structure and key modules
3. research -> Check project docs, issue tracker patterns, PR conventions
4. Document -> Contributor-focused guide: where to add code, test patterns,
PR expectations, coding style
5. Present -> "Here's how this project works and how to contribute..."
Guardrails
Read-only. Onboard never modifies source code. It only reads and analyzes.
Start broad, go deep. Always provide the high-level overview before diving into details.
Show, don't just tell. Use diagrams for architecture, code snippets for patterns, examples for conventions.
Admit uncertainty. If the "why" behind a design decision is unclear, say so rather than guessing.
Respect scope. If asked about one module, don't dump the entire codebase analysis.
Update, don't rebuild. If the codebase was previously onboarded and stored in memory, only re-scan changed areas.
Tailor to the audience. Junior developers need more explanation; architects need more diagrams and trade-off analysis.
Always include "how to get started." The most important outcome is that the reader can set up and run the project.
