espennilsen/pi / skills/handoff
handoff
VerifiedGenerate a self-contained handoff prompt that lets the user 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"
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.4 KB |
SKILL.md
View on GitHub---
name: handoff
description: >
Generate a self-contained handoff prompt that lets the user 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.
```bash
# Project identity
basename $(pwd)
git remote -v 2>/dev/null | head -2
# Branch and recent work
git branch --show-current 2>/dev/null
git log --oneline -10 2>/dev/null
# Uncommitted changes (critical for handoff)
git status --short 2>/dev/null
git diff --stat 2>/dev/null
# Stashed work
git stash list 2>/dev/null
# Any running processes or dev servers the user should know about
# (mention if relevant to the task)
```
### 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.
````markdown
```
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
1. Present the handoff prompt inside a single fenced code block so it's easy to copy
2. If there are uncommitted changes, mention this outside the code block as a reminder
3. Optionally suggest saving the prompt to a file: `pbcopy` or write to `.handoff.md`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |