| name | handoff |
| description | Generate a self-contained handoff prompt that lets the user/agent to continue work in a fresh coding agent session with empty context. The prompt captures everything a new agent needs: project, goal, progress, decisions, current state, and remaining work.
**Triggers — use this skill when:** - User says "handoff", "hand off", "hand-off" - User asks to "generate a continuation prompt" - User says "give me a prompt to continue this" - User asks to "wrap up for a new session" - User says "context transfer", "session transfer" - User asks "how do I pick this up later" - User wants to "pass this to another agent"
|
Handoff — Session Context Transfer
Generate a self-contained prompt that a fresh coding agent (with zero prior context) can use to seamlessly continue the current work.
Philosophy
Context is expensive. When a session hits its limit, or you want to switch tools, the work-in-progress knowledge shouldn't evaporate. A good handoff prompt is:
- Self-contained — no references to "our earlier conversation"
- Actionable — the new agent knows exactly what to do next
- Honest — clearly states what's done, what's broken, and what's uncertain
- Minimal — includes only what's needed, not a transcript of the old session
Workflow
Step 1 — Gather State
Collect facts from the codebase. Do not rely on conversation memory alone — verify against the filesystem.
basename $(pwd)
git remote -v 2>/dev/null | head -2
git branch --show-current 2>/dev/null
git log --oneline -10 2>/dev/null
git status --short 2>/dev/null
git diff --stat 2>/dev/null
git stash list 2>/dev/null
Step 2 — Synthesize Context from the Session
Review the conversation to extract:
| Element | Question to answer |
|---|
| Goal | What is the user ultimately trying to accomplish? |
| Scope | What specific task was this session focused on? |
| Completed | What has been done? (commits, files created/edited, commands run) |
| In-progress | What was being worked on when the handoff was requested? |
| Remaining | What still needs to be done? |
| Decisions | What architectural or design choices were made and why? |
| Blockers | Any issues, bugs, or unknowns that the next session should know about? |
| Key files | Which files are most relevant to the current task? |
Step 3 — Generate the Handoff Prompt
Produce a single Markdown code block containing the prompt. The user copies this into their next session.
Handoff Prompt Template
Use this structure. Adapt and omit sections as needed — a trivial task doesn't need architectural decisions. The prompt should be as short as possible while remaining complete.
```
Project: <name> — <one-line description>
Path: <absolute path to project root>
Branch: <current branch>
## Goal
<What the user is trying to accomplish — the big picture.>
## Context
<Brief project context the new agent needs. Tech stack, relevant architecture,
anything non-obvious about the codebase.>
## What's Been Done
- <Completed item 1 — be specific: files changed, commits made>
- <Completed item 2>
- ...
## Current State
<What state is the codebase in right now? Clean? Dirty files? Failing tests?
Mention uncommitted changes explicitly — the new agent should not accidentally
discard or duplicate work.>
Dirty files:
- <path/to/file — what was changed and why>
- ...
## What's Left
1. <Next concrete step — this is what the new agent should do first>
2. <Subsequent step>
3. ...
## Key Decisions
- <Decision 1: what was chosen and why>
- <Decision 2>
## Key Files
- `<path>` — <why this file matters for the current task>
- `<path>` — <description>
## Gotchas
- <Anything surprising, non-obvious, or easy to get wrong>
```
Guidelines
Be Specific, Not Vague
- ❌ "We updated the config"
- ✅ "Added
pi-heartbeat settings block to settings.json.example with all 6 fields"
Include Dirty File Details
Uncommitted changes are the most fragile part of a handoff. List every dirty file with a brief note on what changed. If there's a large diff, summarize the intent rather than listing every line.
State the Next Action Clearly
The first item under "What's Left" should be an unambiguous instruction the new agent can act on immediately. Not "continue the refactor" but "refactor src/parser.ts to use the new TokenStream class — the interface is defined in src/types.ts:42".
Keep It Proportional
- Quick fix session → 10-15 line handoff
- Multi-file feature session → 30-50 line handoff
- Major refactor → up to 80 lines, but no more
Don't Include
- Full file contents (the agent can read them)
- Conversation transcript or reasoning history
- Obvious project facts the agent will discover from
package.json etc.
- Emotional context ("we struggled with this" — just state the facts)
Output
- Present the handoff prompt inside a single fenced code block so it's easy to copy
- If there are uncommitted changes, mention this outside the code block as a reminder
- Optionally suggest saving the prompt to a file:
pbcopy or write to .handoff.md
