You finish the handover doc. You think it's clear. Then the new hire opens it and asks: "…where do I even start?"
A Claude Code skill that writes the docs so that never happens.
handover-docs produces handover / onboarding / handbook / README / runbook
documentation structured the way a person actually reads — a front door that
routes by who they are, task-scoped pages (open one page to do one job), clean
durable links, and real prose instead of bullet skeletons. It's the authoring
counterpart to fresh-eyes-review:
write with this, verify with that.
Most handover docs are written from the author's head: organized like the system (modules, layers, services), dense, and front-loaded with the heaviest reference file. The reader inherits a pile and has to reassemble their actual task out of it. So the questions come back:
"Where do I start?" · "What's
M28b?" · "This link is dead." · "Which doc is current?" · "never mind, I'll just ask you every time."
Asking an LLM to "write some docs" usually makes this worse — you get a tidy wall of headings and bullets that looks complete but doesn't actually walk a human through anything.
handover-docs flips the organizing principle: the reader's path is the
structure. Docs are laid out by what the reader came to do, in layers they
descend only as far as their task needs:
Front door → routes by who you are
Orientation → what this is, in 5 minutes
Task pages → "I need to do X" — one page, start to finish
Reference → "what is this part"
Why / ADRs → linked, never copied
Glossary → every internal code, decoded
It then enforces the boring discipline that keeps docs alive: clean relative links anchored to headings and function names, never line numbers; one source of truth for every value and rationale; and every section written as real prose with worked examples.
| 🚪 A routing front door | A README whose first screen says "if you are a new dev → here, QA → here, need a term → glossary" |
| 🧭 A short orientation | "What is this, in 5 minutes" — where things live, what to read next |
| 🛠️ Task-scoped pages | One page per job, titled by the verb, doable start-to-finish without scrolling the whole repo |
| 🔗 Clean, durable links | Relative paths + heading/symbol anchors — no line numbers, no machine paths, slugs verified |
| 🧩 A glossary | Every internal code (M28c, HB-07, 8e, domain terms) decoded, one click from where it's used |
| 📐 Stable numbering | Predictable section/page codes (§4A, HB-07) so cross-references survive edits |
Two modes: write a new set from scratch (the default), or refactor a sprawling existing set into this style in small reviewable steps.
When invoked, the skill:
- Confirms scope + readers — what's being documented, where it lives, who reads it, and what tasks each reader performs. The reader's tasks are the structure, so this is the key input.
- Inventories what exists — reuses and links to good material instead of duplicating it (duplication is drift on day one).
- Proposes a doc map — the file tree + link graph — and gets a quick OK before writing. Cheapest moment to fix the structure.
- Writes top-down — front door and orientation first, then task pages, reference, glossary — each in a per-page template, as real prose.
- Runs a linking pass — every link relative, resolvable, anchored to a stable target, slug verified.
- Self-checks and hands off — recommends a
fresh-eyes-reviewblind read before the docs go to the team.
The core rule: documentation is organized the way the reader arrives, not the way the system is built. Every other rule serves one test — can a real person, opening this cold, get to work without messaging the author?
Skills live in Claude Code's skills directory — ~/.claude/skills/ (global,
available in every project) or a repo's own .claude/skills/ (one project only).
This repo is the skill folder itself (SKILL.md at its root), so clone it
straight in:
Global (available in every project):
git clone https://github.com/kcholakorn/handover-docs.git \
~/.claude/skills/handover-docsPer-project (one repo only):
git clone https://github.com/kcholakorn/handover-docs.git \
<your-repo>/.claude/skills/handover-docsUpdate later with git -C ~/.claude/skills/handover-docs pull.
New skills are picked up the next time you start Claude Code.
Open Claude Code in the project you want to document, then run the skill directly:
/handover-docs
…or just ask in plain language:
Write a handover handbook for this pricing engine so the dev team can take it over.
Restructure the docs in docs/ into a reader-first layout — they're a mess right now.
The skill confirms the readers and their tasks, proposes a doc map for your OK, then writes (or restructures) the set.
handover-docs is one half of a loop:
| Skill | Role | |
|---|---|---|
| ✍️ Write | handover-docs | Produces / restructures the docs |
| 🔍 Verify | fresh-eyes-review | Reads them back as real humans; reports where the team would bounce them |
write → fresh-eyes (blind) → fix → re-check → ship.
Does it just generate a wall of headings like every other "write docs" prompt? No — that's the failure mode it's built against. It writes prose with worked examples, refuses bullet-skeleton sections, and structures by the reader's tasks, not the system's modules.
Why does it care so much about links? Because dead and rotting links are the fastest way to lose a reader's trust. It anchors to headings and function names (which move with their content) instead of line numbers (which break the instant anyone edits above them), and verifies every anchor slug rather than guessing it.
Will it overwrite my existing docs?
It writes and edits docs (unlike fresh-eyes-review, which is read-only). In
refactor mode it works in small, reviewable steps and preserves good existing
prose — it reorganizes and links rather than rewriting for its own sake. Use
version control and review the diffs, as with any authoring tool.
Does it handle code-generated API reference? No. It writes human-facing handover/onboarding/handbook docs. API reference from code, inline code comments, and marketing copy are out of scope.
Is it tied to a specific stack or language? No — it's generic. The doctrine (reader-first layering, clean links, single source of truth) applies to any project. It matches the surrounding docs' house style, including bilingual conventions.
Issues and pull requests welcome — especially per-page template variants, additional refactor diagnostics, and real-world "this is what made our handover land" examples.
Released under the MIT License.