# Codebase Onboarding

> Skill — Codebase Onboarding

- Skill: `sairam0424/codebase-onboarding` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sairam0424/codebase-onboarding`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sairam0424/codebase-onboarding/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: sairam0424 (https://skillmd.com/u/sairam0424)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sairam0424/codebase-onboarding

---


# Skill — Codebase Onboarding

## When this skill activates

When entering a new or unfamiliar repository for the first time, when asked to
summarize or map a codebase, or when needing to build a mental model before
making changes. Also activates when explicitly asked to generate an onboarding
report or learning path.

## Mandatory actions when this skill is active

Execute the following auto-summarization pipeline in order:

### Step 1 — Detect Stack

Identify the technology stack by examining:

- **Language(s)**: file extensions, shebang lines, language-specific config files
- **Framework(s)**: package.json dependencies, requirements.txt, go.mod, Cargo.toml
- **Build system**: Makefile, webpack, vite, turbopack, gradle, cargo, mix
- **Test framework**: jest, pytest, vitest, go test, RSpec, xUnit
- **Package manager**: npm, yarn, pnpm, pip, poetry, cargo, go modules
- **Infrastructure**: Docker, Kubernetes, Terraform, CDK, serverless configs

### Step 2 — Find Entry Points

Locate all entry points into the application:

- Main files (main.ts, index.ts, app.py, main.go, Program.cs)
- CLI entry points (bin/ directory, package.json bin field)
- Route definitions (router files, controller registrations)
- Event handlers (message consumers, cron jobs, webhook handlers)
- Worker/queue processors
- Migration entry points (seed files, migration runners)

### Step 3 — Build Module Dependency Graph

Create a graph where:

- **Nodes** = modules, packages, or major source directories
- **Edges** = imports, function calls, event emissions between modules
- Identify circular dependencies (flag as architectural debt)
- Note external service dependencies (databases, APIs, queues)

### Step 4 — Identify Hot Paths

Find the most critical files by measuring:

- **Most imported**: files that appear in the most import statements
- **Most modified**: files with the highest git commit frequency (last 90 days)
- **Largest fan-out**: files that import the most other modules
- **Gateway files**: files that bridge between major subsystems

### Step 5 — Generate Learning Path

Create an ordered reading list that builds understanding progressively:

1. Configuration files (understand the shape of the project)
2. Entry points (understand how the system starts)
3. Core domain logic (understand what the system does)
4. Infrastructure/adapters (understand how it connects to the world)
5. Edge cases and error handling (understand failure modes)
6. Tests (understand expected behavior and invariants)

### Step 6 — Output Report

Write `ONBOARDING-REPORT.md` to `.planning/` containing:

- Stack summary (one-line per technology)
- Entry points list (file path + purpose)
- Dependency graph (ASCII or Mermaid format)
- Hot paths table (file, import count, commit frequency)
- Learning path (ordered reading list with file paths)
- Key architectural decisions or patterns observed
- Known debt or areas of concern

## Self-check before task completion

Before marking a task done when this skill was active:

- [ ] Did I identify the stack correctly (language, framework, build, test)?
- [ ] Did I find ALL entry points (not just the obvious main file)?
- [ ] Did I build a dependency graph showing module relationships?
- [ ] Did I identify hot paths (most-imported and most-modified)?
- [ ] Did I create a usable learning path (ordered, progressive)?
- [ ] Did I output ONBOARDING-REPORT.md to .planning/?
- [ ] Is the report useful to someone with zero prior context?