wiki-onboarding

by microsoft

Generates four audience-tailored onboarding guides in an onboarding/ folder — Contributor, Staff Engineer, Executive, and Product Manager. Use when the user… npx skills add https://github.com/microsoft/agent-skills --skill wiki-onboarding Download ZIPGitHub2.7k

Wiki Onboarding Guide Generator

Generate four audience-tailored onboarding documents in an onboarding/ folder, each giving a different stakeholder exactly the understanding they need.

Source Repository Resolution (MUST DO FIRST)

Before generating any guides, you MUST determine the source repository context:

• Check for git remote: Run git remote get-url origin to detect if a remote exists

• Ask the user: "Is this a local-only repository, or do you have a source repository URL (e.g., GitHub, Azure DevOps)?"

• Remote URL provided → store as REPO_URL, use linked citations: [file:line](REPO_URL/blob/BRANCH/file#Lline)

• Local-only → use local citations: (file_path:line_number)

• Determine default branch: Run git rev-parse --abbrev-ref HEAD

• Do NOT proceed until source repo context is resolved

When to Activate

• User asks for onboarding docs or getting-started guides

• User runs /deep-wiki:onboard command

• User wants to help new team members understand a codebase

Output Structure

Generate an onboarding/ folder with these files:

onboarding/
├── index.md # Onboarding hub — links to all 4 guides with audience descriptions
├── contributor-guide.md # For new contributors (assumes Python or JS background)
├── staff-engineer-guide.md # For staff/principal engineers
├── executive-guide.md # For VP/director-level engineering leaders
└── product-manager-guide.md # For product managers and non-engineering stakeholders

index.md — Onboarding Hub

A landing page with:

• One-paragraph project summary

• Guide selector table:

Guide Audience What You'll Learn Time Contributor Guide New contributors with Python/JS experience Setup, first PR, codebase patterns ~30 min Staff Engineer Guide Staff/principal engineers Architecture, design decisions, system boundaries ~45 min Executive Guide VP/directors of engineering Capabilities, risks, team topology, investment thesis ~20 min Product Manager Guide Product managers Features, user journeys, constraints, data model ~20 min

Language Detection

Scan the repository for build files to determine the primary language for code examples:

• package.json / tsconfig.json → TypeScript/JavaScript

• *.csproj / *.sln → C# / .NET

• Cargo.toml → Rust

• pyproject.toml / setup.py / requirements.txt → Python

• go.mod → Go

• pom.xml / build.gradle → Java

Guide 1: Contributor Guide

File: onboarding/contributor-guide.md Audience: Engineers joining the project. Assumes proficiency in Python or JavaScript and general software engineering experience. Length: 1000–2500 lines. Progressive — each section builds on the last.

Required Sections

Part I: Foundations (skip if repo uses Python or JS)

• {Primary Language} for Python/JS Engineers — Syntax comparison tables, async model, collections, type system, package management. Concrete code side-by-side, NOT abstract descriptions.

• {Primary Framework} Essentials — Compare to equivalent Python/JS frameworks (e.g., FastAPI, Express). Request pipeline, routing, DI, config.

Part II: This Codebase 3. What This Project Does — 2-3 sentence elevator pitch 4. Project Structure — Annotated directory tree (what lives where and why). Include graph TB architecture overview. 5. Core Concepts — Domain-specific terminology explained with code examples. Use erDiagram for data model. 6. Request Lifecycle — sequenceDiagram (with autonumber) tracing a typical request end-to-end. 7. Key Patterns — "If you want to add X, follow this pattern" templates with real code

Part III: Getting Productive 8. Prerequisites & Setup — Table: Tool, Version, Install Command. Step-by-step with expected output at each step. 9. Your First Task — End-to-end walkthrough of adding a simple feature 10. Development Workflow — Branch strategy, commit conventions, PR process. Use flowchart diagram. 11. Running Tests — All tests, single file, single test, coverage commands 12. Debugging Guide — Common issues table: Symptom, Cause, Fix 13. Common Pitfalls — Mistakes every new contributor makes and how to avoid them

Appendices

• Glossary (40+ terms)

• Key File Reference — Table: Path, Purpose, Why It Matters, Source

• Quick Reference Card — Cheat sheet of most-used commands and patterns

Rules

• All code examples in the detected primary language

• Every command must be copy-pasteable with expected output

• Minimum 5 Mermaid diagrams (architecture, ER, sequence, flowchart, state)

• Use Mermaid for workflow diagrams (dark-mode colors) — add <!-- Sources: ... --> comment block after each

• Ground all claims in actual code — cite using linked format

Guide 2: Staff Engineer Guide

File: onboarding/staff-engineer-guide.md Audience: Staff/principal engineers who need the "why" behind every decision. Deep systems experience, may not know this repo's language. Length: 800–1200 lines. Dense, opinionated, architectural.

Required Sections

• Executive Summary — What the system is in one dense paragraph. What it owns vs delegates.

• The Core Architectural Insight — The SINGLE most important concept. Include pseudocode in a DIFFERENT language from the repo.

• System Architecture — Full Mermaid graph TB diagram. Call out the "heart" of the system.

• Domain Model — Mermaid erDiagram of core entities. Data invariants table: Entity, Invariant, Enforced By, Source.

• Key Abstractions & Interfaces — classDiagram showing load-bearing abstractions.

• Request Lifecycle — sequenceDiagram (with autonumber) showing typical request from entry to response.

• State Transitions — stateDiagram-v2 for entities with meaningful lifecycle states.

• Decision Log — Table: Decision, Alternatives Considered, Rationale, Source.

• Dependency Rationale — Table: Dependency, Purpose, What It Replaced, Source.

• Data Flow & State — How data moves through the system. Storage comparison table.

• Failure Modes & Error Handling — flowchart for error propagation paths.

• Performance Characteristics — Bottlenecks, scaling limits, hot paths.

• Security Model — Auth, authorization, trust boundaries, data sensitivity.

• Testing Strategy — What's tested, what isn't, testing philosophy.

• Known Technical Debt — Table: Issue, Risk Level, Affected Files, Source.

• Where to Go Deep — Recommended reading order of source files, links to wiki sections.

Rules

• Use pseudocode in a different language to explain concepts

• Use comparison tables to map unfamiliar concepts (e.g., Task<T> = Awaitable[T])

• Dense prose with tables, NOT shallow bullet lists

• Every claim backed by linked citation

• Minimum 5 Mermaid diagrams (architecture, ER, class, sequence, state, flowchart)

• Each diagram followed by <!-- Sources: ... --> comment block

• Use tables aggressively — decisions, dependencies, debt should ALL be tables with Source columns

• Focus on WHY decisions were made, not just WHAT exists

Guide 3: Executive Guide

File: onboarding/executive-guide.md Audience: VP/director of engineering. Needs capability overview, risk assessment, and investment context — NOT code-level details. Length: 400–800 lines. Strategic, concise, decision-oriented.

Required Sections

• System Overview — What it does, who uses it, business value in 2-3 sentences

• Capability Map — Table: Capability, Status (Built/Partial/Planned), Maturity, Dependencies. What the system can and cannot do today.

• Architecture at a Glance — High-level Mermaid graph LR diagram. Services, data stores, external integrations — NO internal code details. Focus on deployment units and team boundaries.

• Team Topology — Which team/person owns which components. Table: Component, Owner, Criticality, Bus Factor.

• Technology Investment Thesis — Why these technologies were chosen. Table: Technology, Purpose, Alternatives Considered, Risk Level.

• Risk Assessment — Table: Risk, Likelihood, Impact, Mitigation, Owner. Cover reliability, security, scalability, compliance.

• Cost & Scaling Model — How costs scale with usage. What the bottlenecks are. When the next scaling investment is needed.

• Dependency Map — graph TB showing critical external dependencies. Table: Dependency, Type (Service/Library/Platform), Risk if Unavailable.

• Key Metrics & Observability — What's measured, what dashboards exist, alerting coverage. Table: Metric, Current Value, Target, Source.

• Roadmap Alignment — Engineering workstreams mapped to business priorities. What's in progress, what's planned, what's blocked.

• Technical Debt Summary — Top 5 debt items with business impact. Table: Issue, Business Impact, Effort to Fix, Priority.

• Recommendations — 3-5 actionable recommendations for the next quarter, prioritized by impact.

Rules

• NO code snippets — this guide is for engineering leaders, not coders

• Diagrams at service/team level, not class/function level

• Every claim backed by evidence — cite wiki sections, architecture docs, or source files

• Minimum 3 Mermaid diagrams (architecture overview, dependency map, capability/roadmap)

• Tables for every structured finding — this audience reads tables, not prose

• Business language — translate technical concepts into impact (reliability, velocity, cost, risk)

Guide 4: Product Manager Guide

File: onboarding/product-manager-guide.md Audience: Product managers and non-engineering stakeholders. Needs to understand what the system does, what's possible, and where the boundaries are — NOT how it's built. Length: 400–800 lines. User-centric, feature-focused, constraint-aware.

Required Sections

• What This System Does — 2-3 sentence elevator pitch in user-facing language (no jargon)

• User Journey Map — Mermaid graph LR or journey diagram showing primary user flows through the system

• Feature Capability Map — Table: Feature, Status (Live/Beta/Planned/Not Possible), User-Facing Behavior, Limitations. Comprehensive map of what's built and what's not.

• Data Model (Product View) — Simplified Mermaid erDiagram showing entities users interact with. Explain in business terms (e.g., "A Project has many Documents" not "FK relationship").

• Configuration & Feature Flags — Table: Flag/Config, What It Controls, Default, Who Can Change It. What can be toggled without engineering work.

• API Capabilities — What integrations are possible. Table: Capability, Endpoint/Method, Authentication, Rate Limits. Written for integration partners, not developers.

• Performance & SLAs — Response times, throughput limits, availability targets. Table: Operation, Expected Latency, Throughput Limit, Current SLA.

• Known Limitations & Constraints — Honest list of what the system can't do or does poorly. Table: Limitation, User Impact, Workaround, Planned Fix.

• Data & Privacy — What data is collected, where it's stored, retention policies, compliance status. Table: Data Type, Storage Location, Retention, Compliance.

• Glossary — Domain terms explained in plain language (not engineering jargon)

• FAQ — 10+ common questions a PM would ask, answered concisely

Rules

• ZERO engineering jargon — no "middleware", "dependency injection", "ORM". Use plain language.

• User-centric framing — describe everything in terms of what users experience, not how code works

• Minimum 3 Mermaid diagrams (user journey, data model, feature map/capability overview)

• Tables for every structured finding — PMs scan tables, not prose

• If a technical concept must be mentioned, explain it in one sentence (e.g., "Feature flags — toggles that let us turn features on/off without deploying code")

• Every claim grounded in evidence — cite wiki sections or source files for verification

Mermaid Diagram Rules (ALL guides)

ALL diagrams must use dark-mode colors:

• Node fills: #2d333b, borders: #6d5dfc, text: #e6edf3

• Subgraph backgrounds: #161b22, borders: #30363d

• Lines: #8b949e

• If using inline style directives, use dark fills with ,color:#e6edf3

• Do NOT use <br/> in Mermaid labels (use <br> or line breaks)

Validation

After generating each guide, verify:

• All file paths mentioned actually exist in the repo

• All class/method names are accurate (not hallucinated)

• Mermaid diagrams render (no syntax errors)

• No bare HTML-like tags (generics like List<T>) outside code fences — wrap in backticks

• Each guide is appropriate for its audience — no code in Executive/PM guides