# Handoff

> Use at the end of a session when you want a single self-contained prompt that bootstraps a fresh, zero-context conversation - switching chats, clearing context, hitting the context limit, or moving to another machine, with no runbook or audit trail in play. Produces a prompt a brand-new Claude (no memory of this session) can act on immediately. Triggers: "handoff", "/handoff", "write the prompt for a new chat", "I'm clearing context - give me a prompt to continue", "hand this off to a fresh session". Not for handoffs partway through a procedure that keeps its own on-disk audit trail - use whatever skill links that trail instead.

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

---


# Handoff - Self-Contained Next-Session Prompt

## Overview

Produce **one prompt** that a fresh Claude - with zero memory of this conversation - can act on immediately. The defining constraint: the next session starts with **0 context**. Everything it needs to continue must live *inside the prompt text*. No "as we discussed", no nickname left undefined, no bare file path the reader can't place.

Standalone by design: no runbook, no audit trail, no persisted repo file. Just the prompt.

## When to use

- Wrapping up; you'll continue this work in a new chat (clearing context, hitting the context limit, switching machines).
- You want a copy-pasteable brief that stands entirely on its own.

**Not** when you're partway through a procedure that already keeps its own audit trail on disk. A handoff that ignores that trail duplicates it and the two drift. If your setup has a handoff skill that links the procedure and its audit files, use that one - `claude-ssh-partner` ships `runbook-handoff` for exactly this case.

## What you produce

One artifact, two channels carrying **identical bytes**:
1. **Stdout** - in a fenced ` ```markdown ` block.
2. **macOS clipboard** - via `pbcopy`.

No repo file. No commit.

## Procedure

### 1. Gather state (read-only)

Pull what the next session needs from this one:
- `git status` + `git diff --stat` and `git log -8 --oneline` - committed vs uncommitted work.
- `TaskList` - any in-progress / pending items.
- The conversation's goal, the key files touched, and any decisions or dead-ends reached.

### 2. Assemble the prompt (the contract)

The prompt MUST contain these sections, in this order. Fill every angle bracket; omit a section only where it's marked optional.

```markdown
# <Topic - one line, e.g. "Finish the retry backoff in the billing worker">

## Goal
<One sentence: what we're trying to achieve.>

## Background
<2-5 sentences a stranger needs. Define every entity the first time it appears -
repo, server, ticket ID, service name. A name with no definition fails the test below.>

## State
<What's done so far. Committed? cite the sha + message. Uncommitted? where, and what.
Current status in one or two lines.>

## Next
<The concrete next action(s), specific and ordered. Not "continue the work" - say
exactly what to do first.>

## Files & commands
- `<absolute/path>` - <one line: what it is / why it matters>
- `<command>` - <what it does>

## Gotchas  (optional - omit if none)
<Constraints, things already tried that didn't work, things NOT to do.>
```

Keep it scannable - roughly one screen. No prose summaries of the conversation.

### 3. Self-containment test (before printing)

Re-read the assembled prompt **as if you had never seen this conversation**. Every name, path, ID, and pronoun ("it", "that", "the issue") must resolve from the prompt text alone. If anything leans on shared memory, rewrite it to name the thing explicitly. This test is the whole point of the skill - do not skip it.

### 4. Deliver

Write the finished prompt to a scratch file and copy it (one Bash call - the quoted heredoc delimiter keeps `$`, backticks, etc. literal):

```bash
cat > /tmp/claude-handoff.md <<'HANDOFF_EOF'
<the exact assembled prompt, verbatim>
HANDOFF_EOF
pbcopy < /tmp/claude-handoff.md
```

Print the **same** text in a fenced ` ```markdown ` block in the chat, then close with one status line:

```
✓ self-contained handoff copied to clipboard - paste into a fresh conversation
```

## Critical rules

- **Zero-context readable.** A reader with no memory of this session can act on it. Define every entity; expand every "it".
- **Same bytes everywhere.** The printed block and the clipboard match exactly.
- **Absolute paths with a one-line gloss** - the next session can't infer your cwd or what a file is for.
- **No prose around the printed block.** The user is copy-pasting.
- **No file in the repo, no commit.** The prompt is ephemeral; its home is the next conversation.
- **No follow-up suggestions.** The handoff prompt itself contains the next action.