# Handoff

> Write or consume a standardized handoff document so work can continue in a fresh chat. Use for 'make a handoff', 'write a handoff doc', or when a session opens pointing at a handoff file to continue from it.

- Skill: `dylanpulver/handoff` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dylanpulver/handoff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dylanpulver/handoff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dylanpulver (https://skillmd.com/u/dylanpulver)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dylanpulver/handoff

---


# handoff

A core meta-workflow: plan in one chat → handoff → execute in a fresh chat. Without a standard,
the same handoff-request template gets retyped over and over and orphaned HANDOFF-*.md files
litter repo roots. This standardizes both directions.

## Write mode (`/handoff <topic>` or "make a handoff")

1. Write to **`.claude/handoffs/<topic>-YYYY-MM-DD.md`** (create dir; never the repo root).
2. Sections, in order — self-contained enough that a cold session needs nothing else:
   - **Goal** — what we're trying to achieve, in one paragraph
   - **Architecture / how it works** — only what the executor must know, with real file paths
   - **Decisions made (and why)** — so they don't get re-litigated
   - **Current status** — done / in-flight / not started
   - **Exact next steps** — numbered, concrete, in order
   - **Open questions** — decisions the executor should surface, not make
   - **Artifacts** — files, PRs, URLs, commands that matter
   - **Gotchas** — anything that already bit us once
3. Append one line to `.claude/handoffs/INDEX.md`: date, topic, path, status: **open**.
4. Tell the user the one-liner to start the new chat with: `read .claude/handoffs/<file> and continue`.

## Consume mode (session opens with a handoff path, or `consume <path>`)

1. Read it fully; confirm understanding in 3 lines (goal, next step, first action) — then start.
2. Mark it **consumed** in INDEX.md with today's date and the new session's purpose.
3. **Do not maintain the handoff during execution** — it's a launch document, not a status file
   (standing instruction: "handoff was a 1-time thing"). Ongoing state belongs in `.claude/state.md`
   (whereami skill).

## Hygiene

If you notice stale `HANDOFF-*.md` files in a repo root, offer to move them into `.claude/handoffs/`
and index them — once.