Handoff Skill

Your job is to produce a handoff document — a compact, self-contained markdown file that a brand-new agent (with zero context from this conversation) can read and immediately continue the work effectively.

Why this matters

Agents lose context across sessions. A good handoff document lets work continue without the incoming agent asking "what are we doing?" or making decisions the current session already resolved. Everything the new agent needs should be in the document; nothing else should be assumed.

What to extract from the conversation

Read the full conversation carefully. Pull out:

1. Goal — What the user is ultimately trying to accomplish. One sentence.

If the goal shifted during the conversation, note the current goal.

1. Context — Project name, directory, tech stack, key constraints, relevant

background the user shared. Keep it tight — only what shapes decisions.

1. What's been done — Concrete completed actions: files created/edited,

commands run, features implemented, PRs opened. Reference specific file paths and line numbers when known.

1. Key decisions made — Choices that were discussed and settled. Include the

_reason_ — "we chose X because Y" — so the new agent doesn't re-litigate them.

1. Current state — Where things stand right now. What's working, what's

broken, what's half-done. If there are uncommitted changes or a partial implementation, say so.

1. Open items / blockers — What's unresolved, what's blocked and why,

what the user was unsatisfied with.

1. Next steps — Specific, ordered actions for the incoming agent to take.

Write these as imperatives ("Run X", "Edit Y at line Z", "Ask the user about W"). Be concrete enough that the agent can start immediately.

1. User preferences observed — Communication style, things the user

corrected or pushed back on, workflow preferences. This helps the new agent avoid the same friction.

1. Key files — A short list of the most important files, with one-line

descriptions. Not every file touched — only the ones that matter for next steps.

Output format

Write the handoff document in this exact structure (use these headings):

# Handoff: [brief description of the work]

**Date:** [today's date]
**Project:** [project name or path]
**Status:** [one of: In Progress / Blocked / Ready for Review / Done]

## Goal

[One to two sentences.]

## Context

[Bullet list of key background — project, tech stack, constraints.]

## What's Been Done

[Bullet list. Specific. File paths, commands, decisions.]

## Key Decisions

[Bullet list. Each item: decision + reason.]

## Current State

[Short description of where things stand. What's working, what's not, what's partial.]

## Open Items

[Bullet list. Include blockers.]

## Next Steps

1. [First thing the agent should do]
2. [Second thing]
3. [...]

## User Preferences

[Bullet list. Things the user corrected, likes, dislikes, or prefers about working style.]

## Key Files

| File           | Purpose      |
| -------------- | ------------ |
| `path/to/file` | what it does |

Calibrate length to complexity

• Short session (< 20 turns, single task): aim for ~200–350 words
• Medium session: 350–600 words
• Long session with many threads: 600–900 words. Do NOT exceed 1000 words — if it

can't fit, you're summarizing at too fine a grain. Prioritize next steps, current state, and key decisions over exhaustive history.

Delivery

1. Write the handoff document to a file: handoff-YYYYMMDD-TITLE.md in the current working

directory (or wherever the project files are).

1. Also print the full content in the conversation so the user can see and copy it.

1. After printing, say one sentence about what the incoming agent should do first.

What NOT to include

• Conversation filler, pleasantries, or anything that doesn't help the new agent act
• Duplicate information (say each thing once)
• Long code blocks — reference the file and line instead
• Speculation about future work beyond what the user discussed
• Tool outputs or command results verbatim — summarize them