Codebase Onboarding
Analyze any codebase and generate production-quality onboarding documentation tailored to the audience. Produces architecture overviews with system diagrams, annotated key file maps, step-by-step local setup guides, common developer task runbooks, debugging guides with real error solutions, and contribution guidelines. Supports Markdown, Notion, and Confluence output formats.
Core Capabilities
- Architecture analysis — tech stack identification from manifests/lockfiles, system boundary mapping, Mermaid data-flow diagrams, dependency graphs, module ownership.
- Key file annotation — surface the 20 most important files and why they matter; mark entry points, config hubs, shared utilities, and files dangerous to modify without coordination.
- Setup guide generation — prerequisites with exact versions,
git clone-to-tests steps, env-var docs, infra setup (Docker/DB/cache), and a verification checklist.
- Task runbooks — add an API endpoint, run/write tests, create & apply migrations, deploy to staging/production, add a dependency safely.
- Debugging guide — common errors with exact messages and fixes, log locations by environment, diagnostic SQL/CLI queries, local reproduction of production issues.
- Audience-aware output — tailored additions for junior developers, senior engineers, and contractors; Markdown / Notion / Confluence formats.
Keywords: codebase onboarding, developer experience, documentation, architecture overview, setup guide, debugging guide, contribution guidelines, code walkthrough, new hire onboarding
When to Use
- Onboarding a new team member (junior, senior, or contractor)
- After a major refactor that made existing docs stale
- Before open-sourcing a project
- Creating a team wiki page for a service you own
- Self-documenting before a long vacation or team transition
- Preparing for a compliance audit that requires documentation
Clarify First
Before generating the docs, confirm these inputs. If any is unknown or vague, ASK — do not assume:
Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.
Tools
| Tool |
Purpose |
Command |
architecture_mapper.py |
Analyze project structure and generate a high-level architecture map |
python scripts/architecture_mapper.py /path/to/project --json |
onboarding_generator.py |
Scan a project directory and generate an onboarding guide |
python scripts/onboarding_generator.py /path/to/project --json |
setup_validator.py |
Validate a project's development setup completeness |
python scripts/setup_validator.py /path/to/project --json |
All tools accept an optional directory argument (default: current directory) and --json for machine-readable output.
References
Load the reference that matches the task — keep this file lean and pull detail on demand:
- references/fact-gathering-and-patterns.md — the Phase 1 fact-gathering shell commands and the Phase 2 architecture-pattern classification table. Read when analyzing a codebase before writing docs.
- references/documentation-templates.md — the architecture overview, key file map, local setup, and debugging guide templates plus audience-specific (junior/senior/contractor) additions. Read when generating the actual onboarding documents.
- references/quality-and-best-practices.md — quality verification checklist, common pitfalls, best practices, a troubleshooting matrix, and success criteria. Read before shipping onboarding docs.
Scope & Limitations
This skill covers:
- Generating architecture overviews, key file maps, setup guides, task runbooks, and debugging guides from codebase analysis
- Audience-aware documentation tailored for junior developers, senior engineers, and contractors
- Output in Markdown, Notion, and Confluence formats
- Quality verification checklists and freshness audit processes
This skill does NOT cover:
- Automated API reference generation from code annotations — see
engineering/changelog-generator for release-oriented docs or engineering/api-design-reviewer for API quality
- Continuous documentation pipelines or CI-triggered doc builds — see
engineering/ci-cd-pipeline-builder for pipeline automation
- Security-focused documentation such as threat models or access control matrices — see
engineering/skill-security-auditor for security auditing
- Runbook generation for incident response and production operations — see
engineering/runbook-generator for operational runbooks
Integration Points
| Skill |
Integration |
Data Flow |
engineering/runbook-generator |
Onboarding task runbooks can seed operational runbooks for production incident response |
Onboarding runbook templates → Runbook Generator for ops-grade expansion |
engineering/api-design-reviewer |
API route analysis from Phase 1 feeds into API design quality reviews |
Discovered API endpoints → API Design Reviewer for consistency checks |
engineering/database-schema-designer |
Database schema files identified during key file mapping inform schema design reviews |
Schema file paths and ORM type → Schema Designer for migration planning |
engineering/tech-debt-tracker |
Technical debt items surfaced during architecture analysis should be logged for tracking |
Architecture analysis findings → Tech Debt Tracker backlog entries |
engineering/ci-cd-pipeline-builder |
CI/CD config discovered in Phase 1 can be validated and improved by the pipeline builder |
CI config paths and workflow list → Pipeline Builder for optimization |
engineering/dependency-auditor |
Dependency counts and lockfiles gathered in Phase 1 feed directly into security and license audits |
Package manifests and lockfiles → Dependency Auditor for vulnerability scanning |
1---
2name: codebase-onboarding
3description: >
4 Analyze a codebase and generate onboarding docs: architecture overviews, file maps, setup
5 guides, runbooks, and debugging guides. Use when onboarding new team members, open-sourcing,
6 or documenting after a major refactor.
7license: MIT + Commons Clause
8metadata:
9 version: 1.1.0
10 author: borghei
11 category: engineering
12 domain: developer-experience
13 tier: POWERFUL
14 updated: 2026-06-17
15 frameworks: markdown, notion, confluence
16---
17
18# Codebase Onboarding
19
20Analyze any codebase and generate production-quality onboarding documentation tailored to the audience. Produces architecture overviews with system diagrams, annotated key file maps, step-by-step local setup guides, common developer task runbooks, debugging guides with real error solutions, and contribution guidelines. Supports Markdown, Notion, and Confluence output formats.
21
22## Core Capabilities
23
24- **Architecture analysis** — tech stack identification from manifests/lockfiles, system boundary mapping, Mermaid data-flow diagrams, dependency graphs, module ownership.
25- **Key file annotation** — surface the 20 most important files and why they matter; mark entry points, config hubs, shared utilities, and files dangerous to modify without coordination.
26- **Setup guide generation** — prerequisites with exact versions, `git clone`-to-tests steps, env-var docs, infra setup (Docker/DB/cache), and a verification checklist.
27- **Task runbooks** — add an API endpoint, run/write tests, create & apply migrations, deploy to staging/production, add a dependency safely.
28- **Debugging guide** — common errors with exact messages and fixes, log locations by environment, diagnostic SQL/CLI queries, local reproduction of production issues.
29- **Audience-aware output** — tailored additions for junior developers, senior engineers, and contractors; Markdown / Notion / Confluence formats.
30
31**Keywords:** codebase onboarding, developer experience, documentation, architecture overview, setup guide, debugging guide, contribution guidelines, code walkthrough, new hire onboarding
32
33## When to Use
34
35- Onboarding a new team member (junior, senior, or contractor)
36- After a major refactor that made existing docs stale
37- Before open-sourcing a project
38- Creating a team wiki page for a service you own
39- Self-documenting before a long vacation or team transition
40- Preparing for a compliance audit that requires documentation
41
42## Clarify First
43
44Before generating the docs, confirm these inputs. If any is unknown or vague, ASK — do not assume:
45
46- [ ] **Target codebase path** — which project to analyze (the input all three scripts scan)
47- [ ] **Audience** — junior developer, senior engineer, or contractor (tailors which sections appear and at what depth)
48- [ ] **Output format** — Markdown, Notion, or Confluence (sets the generated document format)
49
50Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.
51
52## Tools
53
54| Tool | Purpose | Command |
55|------|---------|---------|
56| `architecture_mapper.py` | Analyze project structure and generate a high-level architecture map | `python scripts/architecture_mapper.py /path/to/project --json` |
57| `onboarding_generator.py` | Scan a project directory and generate an onboarding guide | `python scripts/onboarding_generator.py /path/to/project --json` |
58| `setup_validator.py` | Validate a project's development setup completeness | `python scripts/setup_validator.py /path/to/project --json` |
59
60All tools accept an optional `directory` argument (default: current directory) and `--json` for machine-readable output.
61
62## References
63
64Load the reference that matches the task — keep this file lean and pull detail on demand:
65
66- **[references/fact-gathering-and-patterns.md](references/fact-gathering-and-patterns.md)** — the Phase 1 fact-gathering shell commands and the Phase 2 architecture-pattern classification table. Read when analyzing a codebase before writing docs.
67- **[references/documentation-templates.md](references/documentation-templates.md)** — the architecture overview, key file map, local setup, and debugging guide templates plus audience-specific (junior/senior/contractor) additions. Read when generating the actual onboarding documents.
68- **[references/quality-and-best-practices.md](references/quality-and-best-practices.md)** — quality verification checklist, common pitfalls, best practices, a troubleshooting matrix, and success criteria. Read before shipping onboarding docs.
69
70## Scope & Limitations
71
72**This skill covers:**
73- Generating architecture overviews, key file maps, setup guides, task runbooks, and debugging guides from codebase analysis
74- Audience-aware documentation tailored for junior developers, senior engineers, and contractors
75- Output in Markdown, Notion, and Confluence formats
76- Quality verification checklists and freshness audit processes
77
78**This skill does NOT cover:**
79- Automated API reference generation from code annotations — see `engineering/changelog-generator` for release-oriented docs or `engineering/api-design-reviewer` for API quality
80- Continuous documentation pipelines or CI-triggered doc builds — see `engineering/ci-cd-pipeline-builder` for pipeline automation
81- Security-focused documentation such as threat models or access control matrices — see `engineering/skill-security-auditor` for security auditing
82- Runbook generation for incident response and production operations — see `engineering/runbook-generator` for operational runbooks
83
84## Integration Points
85
86| Skill | Integration | Data Flow |
87|-------|------------|-----------|
88| `engineering/runbook-generator` | Onboarding task runbooks can seed operational runbooks for production incident response | Onboarding runbook templates → Runbook Generator for ops-grade expansion |
89| `engineering/api-design-reviewer` | API route analysis from Phase 1 feeds into API design quality reviews | Discovered API endpoints → API Design Reviewer for consistency checks |
90| `engineering/database-schema-designer` | Database schema files identified during key file mapping inform schema design reviews | Schema file paths and ORM type → Schema Designer for migration planning |
91| `engineering/tech-debt-tracker` | Technical debt items surfaced during architecture analysis should be logged for tracking | Architecture analysis findings → Tech Debt Tracker backlog entries |
92| `engineering/ci-cd-pipeline-builder` | CI/CD config discovered in Phase 1 can be validated and improved by the pipeline builder | CI config paths and workflow list → Pipeline Builder for optimization |
93| `engineering/dependency-auditor` | Dependency counts and lockfiles gathered in Phase 1 feed directly into security and license audits | Package manifests and lockfiles → Dependency Auditor for vulnerability scanning |
borghei