Skip to content
Back to skills

Codebase Handoff

ASecurity

Use when generating or updating a system architecture & handoff HTML document for a repository — produces an interactive tabbed page (Overview, Architecture, Deployment, Database, API, Local Dev) from repo-detectable facts, with Mermaid diagrams. Triggers — "handoff doc", "architecture doc", "document this repo", "generate codebase documentation".

  • 5 stars
  • 0 votes
  • 0 copies
  • 1 view
  • Added November 18, 2026
developmentgoshellnodeapidatabasedocumentation

Works with

  • api

Security analysis

A100/100

Pro scans all 5 files and shows the line behind each finding

Scanned November 18, 2026

npx -y skills add ghalex/skills --skill codebase-handoff --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Codebase Handoff?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Codebase Handoff
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/ghalex-codebase-handoff/badge)](https://www.skillsdirectory.com/skills/ghalex-codebase-handoff)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: codebase-handoff
description: Use when generating or updating a system architecture & handoff HTML document for a repository — produces an interactive tabbed page (Overview, Architecture, Deployment, Database, API, Local Dev) from repo-detectable facts, with Mermaid diagrams. Triggers — "handoff doc", "architecture doc", "document this repo", "generate codebase documentation".
---

# Codebase Handoff Document Generator

Generate a self-contained, interactive HTML handoff document for a repository,
built from **repo-detectable facts only**. Every claim is grounded in a real
source file. Diagrams are authored as **Mermaid text** and rendered in-browser —
never generate image files.

## When to use

When the user wants an architecture / handoff / onboarding document for a
codebase, or to regenerate one.

## Output

A single file at `docs/architecture/handoff.html` in the target repo (or a
user-specified path). Never overwrite an existing `index.html` — if the default
path's `index.html` exists, leave it alone and write `handoff.html`.

## Core rules (non-negotiable)

1. **Evidence first.** Every section ends with a "Source evidence" line listing
   the real files it was built from. If a fact is not found in source, label it
   `inferred` (reasoned from indirect signals) or `not detected` (absent).
   Never invent values, versions, endpoints, or entities.
2. **Names only for secrets.** Environment variables: list names, never values.
3. **Diagrams as Mermaid text.** You write Mermaid; the browser renders it. Never
   produce raster/image files. See `references/mermaid-guide.md`.
4. **Pale, minimalist design.** Copy `references/template.html` verbatim as the
   shell and fill the marked slots. Do not redesign.

## Process — phased, detect → cite → fill

Create one todo per phase. Work them in order. In every phase: detect facts from
source, note the files as evidence, then fill that tab's slot in the template.
Read `references/tab-guides.md` for the exact fields and how to detect each.

- **Phase 0 — Recon → Overview tab.** Scan the repo. Detect languages,
  frameworks, package managers, apps/services (detect monorepos and enumerate
  each app), build & test tools, DB/ORM, API style, deployment tooling, external
  services, existing docs, missing expected docs. Compute the documentation
  completeness score (see tab-guides). This pass also primes every later phase.
- **Phase 1 — Architecture tab.** Components, responsibilities, relationships,
  data flow, request flow, internal + external dependencies. Author the Mermaid
  architecture flowchart with brand logos + pale layer colors (see mermaid-guide).
- **Phase 2 — Deployment & Infrastructure tab.**
- **Phase 3 — Database tab.** Plus **domain-split** Mermaid ER diagrams (every
  table, each entity with PK/FK + key columns + crow's-foot cardinality).
- **Phase 4 — API tab.** Enumerate EVERY endpoint from route source — do NOT rely
  on a README/committed OpenAPI/Postman file for the list (they go stale). Include
  method, full path, auth, and a request/response payload summary per endpoint.
- **Phase 5 — Local Development tab.**
- **Phase 6 — Assemble & verify.** Fill the template, set the repo name / title /
  generated date, write the output file, open it in a browser. Self-review: does
  every section have a "Source evidence" line? Is every uncertain fact labeled
  `inferred`/`not detected`? **Do all Mermaid blocks actually render (no blank
  diagram, no parse error)?** If the architecture diagram is blank, apply the
  mermaid-guide fallback (drop unresolved icons → plain colored nodes).

## How to build the file

1. Read `references/template.html`. Copy it to the output path.
2. Replace the `{{...}}` slots (repo name, generated date, and each tab's body).
3. Keep the `<style>`, the tab-nav JS, and the Mermaid module script unchanged.
4. For each tab, follow `references/tab-guides.md` field-by-field.
5. For diagrams, follow `references/mermaid-guide.md`.

## Reference files

- `references/template.html` — the HTML shell to copy and fill.
- `references/tab-guides.md` — per-tab fields + detection method + evidence rules.
- `references/mermaid-guide.md` — which diagram per tab, syntax, pale theming.

Files in this skill

  • README.md3.8 KB
  • SKILL.md4.2 KB
  • references/mermaid-guide.md9 KB
  • references/tab-guides.md9.3 KB
  • references/template.html8 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in development →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.