Handoff prompt

Handoff prompt

<written by a human being>
 I never get tired of saying this, but the beauty of working with AI is that you can automate even the things you wouldn't have dared to automate not that long ago - because they just weren't worth the time or didn't bring enough value to justify the resources spent on them.

I wrote recently about how important it is to refresh the context window, to not let it overflow when working with AI agents. And to do that, we need to brief the next agent on what’s been happening in the current session.

Yeah, we have agent instructions — but that’s a huge document, and it tends to grow even bigger during a project. Feeding it into every new session would be pointless, because you don’t always need it. Sometimes you just need to carry the conversation chain forward from where you left off and save tokens doing it.

So yesterday I decided to shorten my path to getting a handoff prompt for the next session — so I’m not writing it manually every time, not explaining what I want it to do.

I created a handoff-prompt skill that I can call with a simple slash command in the terminal, and now instead of crafting a request and typing it out in full at the end of every session when I want to reset the context so the agent can write a prompt for the next agent — I just press literally four keys: slash, the first letter of the command (h), Tab, and Enter.

Attaching the skill if anyone needs it.

---
name: handoff-prompt
description: Use when the user wants to hand off the current session to a fresh one — triggers include "/handoff-prompt", "make a handoff", "save progress for next session", "compact session for continuation", "give me a handoff prompt". Produces a copy-pasteable block that lets a new session resume work without losing state.
---

# handoff-prompt

Produce a compact, copy-pasteable prompt that a fresh Claude Code session can use to continue the current work. Do not ask clarifying questions. Output once and stop.

## Token budget

The emitted handoff block MUST be ≤ 300 tokens. If you exceed budget, drop sections in this order until you fit:

1. **Key decisions & gotchas**
2. Compress **Progress so far** to the 3 most load-bearing items
3. **Context references** — keep only the single most relevant path

Never drop: Current task, Where we stopped, Next steps.

## How to gather the content

Introspect this session — do NOT ask the user. Derive each section from what you can see:

- **Current task** — from the user's active goal in recent messages.
- **Progress so far** — from your own tool calls that changed state (Edit, Write, Bash commands that mutated anything, file creations). Cite file paths and, where useful, line numbers.
- **Where we stopped** — your last substantive action plus the reason you paused (end of step, blocker, awaiting user input, tool failure).
- **Next steps** — from any plan/spec/TODO in play, or the obvious continuation of the last action.
- **Key decisions & gotchas** — non-obvious choices or traps surfaced during the session. Include only if real; skip otherwise.
- **Context references** — check the current working directory for `CLAUDE.md`, `AGENTS.md`, and any active plan or spec file (e.g., under `docs/superpowers/plans/` or `docs/superpowers/specs/`). Include their absolute paths. **Never inline their contents.**
- **Open questions** — only if the session has unresolved questions needing user input.

## Output rules

- Emit exactly one fenced markdown code block containing the handoff. One short lead-in line is allowed (e.g., "Paste this into your next session:"). Nothing after the block.
- Omit any section that has no real content — drop the header too, don't leave it empty.
- Terse bullets. Concrete nouns (file paths, commands, line numbers). No filler prose, no restatement of obvious context.
- Write the handoff in second person, as instructions to a fresh agent.
- Reference project context files by absolute path only. Never paste their contents.

## Template

Use this structure inside the fenced block, omitting empty sections:

```
You are continuing a previous Claude Code session. Read the sections below, then continue the work.

## Current task
<1–3 sentences>

## Progress so far
- <file:line or action — terse>

## Where we stopped
<last action + why stopped>

## Next steps
1. <concrete action>

## Key decisions & gotchas
- <non-obvious decision or trap>

## Context references
- CLAUDE.md: <abs path>
- AGENTS.md: <abs path>
- Plan/spec: <abs path>

## Open questions
- <question for the user>
```

## Checklist before emitting

- [ ] One fenced code block, nothing trailing it
- [ ] ≤ 300 tokens inside the block
- [ ] No empty section headers
- [ ] CLAUDE.md / AGENTS.md referenced by path only (if present)
- [ ] Current task, Where we stopped, Next steps all present