Handoff | ProstDev

Note

A long session eventually runs low on context. Rather than let a summary compress away the details that matter, this skill writes them down deliberately — so the next session reads a purpose-built brief instead of reconstructing state from a truncated transcript.

What it does

handoff is a Claude Code skill that writes a single handoff.md at the repo root capturing everything a fresh session needs to continue the work: the goal, what’s done and what’s next, the decisions already made, the files touched, open questions, and a numbered list of concrete next steps.

The point is surviving the context boundary without losing momentum. When a session gets long, you invoke it, it dumps the working state to disk, and you start the next session by pointing Claude at that file. No re-explaining, no re-deriving — the new session opens mid-stride.

When to use it

Invoke it when a session is about to end but the work isn’t:

Context is getting long and you’d rather hand off cleanly than risk an auto-summary dropping details.
You’re stopping for the day on a multi-step task and want tomorrow’s session to resume instantly.
You’re handing the work to a different session (or a teammate’s Claude) and need a self-contained brief.

Important

This is a clean stop/resume checkpoint — not a way to shrink the session you’re in. By the time you invoke it, context is already long; writing the file adds a little more. The payoff is in the next window: a fresh session seeded with ~80 curated lines starts far leaner than one that /compacts the bloated transcript and keeps going. So the honest comparison isn’t “handoff vs. nothing” — it’s:

vs. /compact and continue — compaction is in-place and automatic, but the window still drags along residual tool-output noise. A handoff into a new window has no accumulated cruft — the leanest possible floor. If you just want to keep going right now, /compact is the better tool; a handoff forces a restart for no gain.
vs. a fresh session with no handoff — re-explaining costs more context than the brief does.

Its real weakness is lossiness, not token cost: it captures what Claude thinks matters, so a detail the brief didn’t anticipate has to be re-derived. That’s why the trigger is really “ending a session with work unfinished,” not merely “context is getting long.”

How it works

The skill is a plain Markdown instruction file — no code to run. It tells Claude what to capture and, crucially, how to keep it terse: bullets over prose, under 80 lines, no rehashing the conversation — just state and next actions, with file paths so the next session can jump straight in. A few ideas in here that generalize to any “checkpoint your work” skill:

Write the brief you’d want to receive. The section list (goal, status, decisions, files, blockers, next steps) is exactly what a cold-start reader needs and nothing they don’t.
Constrain the length on purpose. The 80-line cap and “terse bullets, not prose” rule force a signal-dense handoff — a sprawling one is as useless as no handoff at all.
Close the loop for the human. After writing, it tells you the exact phrase to start the next session with, so the round-trip is a copy-paste instead of a thing to remember.

The skill definition

Here’s the actual SKILL.md, verbatim — it’s project-agnostic, so you can drop it into any repo as-is.

---
name: handoff
description: Create a continuation file for picking up this session in a fresh context. Invoke when context is getting long.
---

# Session Handoff

Write a handoff file that a fresh Claude session can read to continue this work.

## Write to

`{RELEVANT_REPO_ROOT}/handoff.md` (overwrite any existing one)

## Include

- **Goal**: What we're trying to accomplish (1-2 sentences)
- **Status**: What's done, what's in progress, what's next
- **Key decisions made**: Architectural choices, trade-offs already resolved
- **Files modified/created**: List with one-line description of changes
- **Blockers or open questions**: Anything unresolved
- **Next steps**: Concrete actions for the next session (numbered)

## Format rules

- Terse bullets, not prose
- Under 80 lines
- No rehashing conversation — just state and next actions
- Include file paths so the next session can jump straight in

## After writing

Tell the user: "Start your next session with: `read /handoff.md and continue from where we left off`"