---
name: write-session-handoff-prompt
description: A prompt that compacts a long AI coding session into a short handoff document a fresh agent can pick up from, with links instead of copies and secrets redacted. Use when the chat is getting too long, context is running out, you are switching agents or tools, or you want to pick the work up later in a new session.
license: MIT
metadata:
  category: coding-prompts
  tags: "handoff,agents,workflow,planning"
  author: johnny-bravo
  version: "1.0"
  updated: "2026-10-31"
  status: published
  aliases: "handoff,session-handoff,context-handoff"
  source_url: "https://github.com/mattpocock/skills/blob/a496f5513d4a4cf889bc48e189e579f4b0bdf6aa/skills/productivity/handoff/SKILL.md"
  source_license: MIT
  copyright: "Copyright (c) 2026 Matt Pocock"
  original_author: "Matt Pocock (mattpocock/skills, 'handoff')"
  modified: "Adapted by TheSkillVault: paste-in prompt with a fixed outline for the document, a focus placeholder instead of command arguments, plain-language steps, how-to-adapt and done-when sections."
  imported_on: "2026-10-31"
---

# Write a session handoff (prompt)

Long AI sessions get slow and forgetful. This prompt makes the AI write a short handoff note. You start a fresh session, give it the note, and carry on where you left off.

## When to use
- The conversation is long and the AI starts forgetting earlier decisions.
- You are moving the work to another agent, tool or teammate.
- You are stopping for the day and want a clean restart next time.

## Steps
1. Paste the prompt below at the end of your current session. Fill in what the next session is for.
2. Check the note it writes. Make sure nothing private slipped in.
3. Start a new session and say: "Read the handoff at <path> and continue."

## Prompt
```text
Write a handoff document so a fresh agent with no memory of this chat can continue the work.

- Save it in my OS temp folder ($TMPDIR, else /tmp; %TEMP% on Windows), not in the project.
  Tell me the full path.
- Next session focus: {{WHAT THE NEXT SESSION IS FOR, or "continue where we left off"}}.
  Tailor the document to that focus.
- Use this outline:
  1. Goal: what we are trying to achieve, in two or three sentences.
  2. Current state: what is done, what works, what is broken right now.
  3. Decisions made, and why (one line each).
  4. Next steps, in order.
  5. Open questions and risks.
  6. Where things are: links or paths to specs, plans, ADRs, issues, branches, commits.
  7. Suggested skills: which skills or prompts the next agent should load.
- Do not copy content that already lives in specs, plans, issues, commits or diffs.
  Point to it by path or URL instead.
- Redact anything sensitive: API keys, passwords, tokens, personal data. Write "[redacted]".
- Keep it short enough to read in two minutes.
```

## How to adapt
- Handing off to a teammate? Add "Write it for a human who knows the codebase but not this chat."
- Want it in the repo? Ask for `docs/handoff.md` instead, but never commit secrets.
- Works with any AI coding tool, including Claude Code, Cursor, Codex or a plain chat.

## Gotchas
- The AI may summarise what it wished happened. Check "Current state" against the actual tests and git status.
- A handoff that copies whole files wastes the next session's context. Links are better.
- Do not paste the note into public places. It can still describe private systems.

## Done when
- The handoff file exists in the temp folder and you know its path.
- A fresh session can state the goal and the next step after reading only that file.

## Example prompt
"This chat is getting long. Write a handoff so a new session can finish the login feature."

---
Adapted from "handoff" in mattpocock/skills by Matt Pocock (MIT). See LICENSE.txt.