# codebase-onboarding

codebase-onboarding — a skill for Claude Code, Codex, Cursor and several other agents that scans a repository and produces onboarding docs: architecture overview, key file map, local setup guide, and debugging reference.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 117 installs · ★ 1183 repo stars
- Author: borghei
- License: LicenseRef-MIT-Commons-Clause · policy=link-only · description only; the file stays with the author
- Source: https://github.com/borghei/Claude-Skills/tree/HEAD/engineering/codebase-onboarding/SKILL.md
- Updated: 2026-11-08
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/borghei-codebase-onboarding

## What it does

The skill ships three Python scripts. `onboarding_generator.py` reads manifests and lockfiles, pulls the stack, entry points, env-var keys, and top-level structure, then writes a draft with `> **TODO (owner):**` markers wherever the agent cannot answer from the files alone. `architecture_mapper.py` detects the project pattern — monorepo, microservices, MVC, or layered — and assigns roles to directories. `setup_validator.py` checks for a README, `.env` template, lockfile, CI config, linter config, tests, and a license, scores the repo from 0 to 100, and lists what to fix.

Output formats are Markdown, Notion, and Confluence. Depth adjusts by audience: junior developer, senior engineer, or contractor each get a different set of sections. The draft from `onboarding_generator.py` is a starting point, not a finished document — the skill marks every gap explicitly so nothing silently gets skipped.

A low score from `setup_validator.py` means the setup guide will have holes, because those gaps are real problems in the repo. Scripts live in `scripts/`, documentation templates in `references/documentation-templates.md`. For a stop-by-stop code tour rather than reference docs, the skill points to `engineering/code-tour`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add borghei/Claude-Skills --skill codebase-onboarding -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/codebase-onboarding/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/codebase-onboarding/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add borghei/Claude-Skills --skill codebase-onboarding -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/codebase-onboarding/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add borghei/Claude-Skills --skill codebase-onboarding -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/codebase-onboarding/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install borghei/Claude-Skills engineering/codebase-onboarding/SKILL.md
```

2. **Manually: put the files in place**
- File: `.github/skills/codebase-onboarding/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add borghei/Claude-Skills --skill codebase-onboarding -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/borghei/Claude-Skills --path engineering/codebase-onboarding
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/codebase-onboarding/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add borghei/Claude-Skills --skill codebase-onboarding -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/borghei/Claude-Skills/tree/HEAD/engineering/codebase-onboarding/SKILL.md

## When to use it
- generate a draft onboarding guide after a major refactor
- score a repository's setup completeness before open-sourcing it
- build a key file map that shows entry points and files dangerous to touch alone
- produce a debugging reference with real error messages and fixes
- document a service before a team transition or long leave

## Example prompts
- Analyze the codebase at `/path/to/project` and generate a Markdown onboarding guide for a junior developer
- Run `setup_validator.py` on this project and list the gaps that would make the setup guide misleading
- Map the key files — entry points, config hubs, shared utilities — and explain why each one matters

## Similar
- [codebase-documenter](https://affpapa.org/en/nevibecode/skills/mhattingpete-codebase-documenter.md) — skill · 595 installs
- [wiki-onboarding](https://affpapa.org/en/nevibecode/skills/wiki-onboarding.md) — skill · 5 installs
- [codebase-summarizer](https://affpapa.org/en/nevibecode/skills/codebase-summarizer.md) — skill · 411 installs
- [c4-codebase-architecture](https://affpapa.org/en/nevibecode/skills/c4-codebase-architecture.md) — skill · ★ 24 repo stars
- [Documentation Architect](https://affpapa.org/en/nevibecode/skills/documentation-architect.md) — skill · 1 install
- [architecture](https://affpapa.org/en/nevibecode/skills/owainlewis-architecture.md) — skill · 331 installs

## Other versions with the same name
- [codebase-onboarding · affaan-m](https://affpapa.org/en/nevibecode/skills/affaan-m-codebase-onboarding.md) — 7300 installs
- [codebase-onboarding · alirezarezvani](https://affpapa.org/en/nevibecode/skills/codebase-onboarding.md) — 698 installs
- [codebase-onboarding · spencerpauly](https://affpapa.org/en/nevibecode/skills/spencerpauly-codebase-onboarding.md) — 527 installs

From the same set: [borghei/claude-skills](https://affpapa.org/en/nevibecode/by/borghei/claude-skills.md) — 120 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
