--- name: handoff description: Use when a session's context is getting long or degrading and you need a detailed, self-contained summary to manually paste into a fresh session (or hand to another machine/tool/teammate). For a short durable fact instead, write it to the persistent memory directory (auto-loaded via MEMORY.md). allowed-tools: Bash, Read metadata: category: claude-config --- # Handoff ## Overview Produce a detailed, self-contained context summary that lets work continue in a brand-new session with no access to this one. By default, print the output to chat for the user to copy and paste. Use File Mode (below) only when a context-threshold nudge requests it or the user explicitly asks for a handoff file. ## When to Use - The current context is long and answer quality is degrading. - You want to start fresh while preserving essential context. - The context window is approaching capacity. - You need to carry context to another machine, tool, or teammate. **Not this skill:** a short durable fact for future sessions → write a memory file in the persistent memory directory and index it in `MEMORY.md` (auto-loaded each session). Never write memory files from `handoff` — the two channels serve different lifetimes. **Handoff-first policy:** if you run a PreCompact hook that intercepts the first auto-compact of a session (this plugin ships none), its interception message makes this skill the first option: print the handoff immediately and tell the user to `/clear` and paste it into the fresh session. Only if the user chooses to keep the session does the next auto-compact proceed normally. If the session has no meaningful work to preserve, say so and stop. ## The Gate — should this be a handoff at all? Ordered tree, run before producing anything; first yes wins. Every move except Continue trades the session — a primary source — for a summary of it, so rule out the cheap options first. (Adapted from mattpocock/skills `PHASE-BOUNDARIES.md`; `/compact` drops out as a rung here because compaction is automated and its pressure is visible in the statusline.) 1. **Can the session just continue?** The next phase needs this phase's reasoning verbatim, or there is comfortable context left. Continue costs nothing and loses nothing. 2. **Is the context irrelevant to what comes next?** Then recommend `/clear` and stop — nothing worth carrying, and the old session stays resumable. Clearing a _relevant_ context is the one-way mistake: the why behind the work doesn't come back from reading the diff. 3. **Is the remaining work a tightly-scoped AFK task?** Send it to a subagent and leave this session untouched — no handoff needed. 4. **Is something actually travelling?** A handoff earns its lossiness only when context must cross a boundary: a new harness or tool, a new machine or directory, a teammate, or a side task forked mid-phase. That list is the whole clause. If nothing travels but the context is degrading anyway, that is the handoff-first case: hand off and `/clear` beats letting auto-compact flatten the decisions. If a hook triggered this — a PreCompact interception, or a context-threshold nudge — the gate is already answered: skip straight to Steps. Make the call at a phase boundary ("ok, we're done with that"), never mid-phase. ## File Mode Use File Mode when a context-threshold nudge fires (the `context-meter` plugin sends one, if you run it) or the user explicitly asks for a handoff file. `log-it` writes its own thin handoff file under its own rules; this section does not govern that file. 1. Write `~/.claude/handoffs/-.md`, and create the directory if needed. 2. Make the first line exactly `cwd: `. Nothing here requires that line, but it is what a SessionStart pickup hook would grep to route the file to the right project, and writing it costs nothing if you add one later. 3. Add a `NEXT MISSION` section containing one short paragraph that tells the successor session what to do first, followed by the standard template below. 4. Tell the user the file path and recommend `/clear` or a new session. Without a pickup hook, the user pastes the file's contents as the first message of the new session (copying the file to the other machine first when the session moves). Or wire a SessionStart hook that surfaces anything in `~/.claude/handoffs/` whose `cwd:` matches the project and archives it once picked up. Archiving belongs to that pickup hook: a hook that surfaces a file archives it, and without a hook nothing surfaces the file a second time, so neither session has an archive step. Never write a handoff file without one of the triggers above. Never commit handoff files. ## Steps 1. **Gather concrete data.** The full conversation and current TODO state are already in your context — use them directly (there is no `session_read`/`todoread` tool in Claude Code). For file changes, run: - `git diff --stat HEAD~10..HEAD` — recent changes - `git status --porcelain` — uncommitted changes 2. **Extract** from the conversation: exact user wording, work completed, decisions, files touched, constraints/preferences established. 3. **Format** using the template below and deliver it through the selected mode. Write in first person ("I did...", "I told you..."). Capture USER REQUESTS and EXPLICIT CONSTRAINTS verbatim — do not paraphrase or invent them. ## Output Template ```plaintext HANDOFF CONTEXT =============== USER REQUESTS (AS-IS) --------------------- - [Exact verbatim user requests - NOT paraphrased] GOAL ---- [One sentence describing what should be done next] WORK COMPLETED -------------- - [First person bullet points of what was done] - [Include specific file paths when relevant] - [Note key implementation decisions] CURRENT STATE ------------- - [Current state of the codebase or task] - [Build/test status if applicable] - [Any environment or configuration state] PENDING TASKS ------------- - [Tasks planned but not completed; next logical steps; blockers] - [Include current TODO state] KEY FILES --------- - [path/to/file] - [brief role description] (Maximum 10 files, prioritized by importance; include files from git diff/status) IMPORTANT DECISIONS ------------------- - [Technical decisions made and why; trade-offs; conventions established] EXPLICIT CONSTRAINTS -------------------- - [Verbatim constraints only - from the user or existing CLAUDE.md/AGENTS.md] - If none, write: None CONTEXT FOR CONTINUATION ------------------------ - [What the next session needs to know; warnings/gotchas; doc references] - Before acting on any status recorded above (tracker, review, store or console, inbox), re-read its source: this handoff records what the writing session believed, and that status may have changed since. ``` The last line of CONTEXT FOR CONTINUATION is fixed text: keep it in every handoff, because the receiving session sees only the handoff and never this skill. ## Format Rules - Plain text with dash bullets — no `#` markdown headers, no bold/italic, no code fences inside the content (so it pastes cleanly as one message). - Workspace-relative file paths. - Pick a length proportional to complexity; include only what matters for continuation. - USER REQUESTS (AS-IS) and EXPLICIT CONSTRAINTS are verbatim only. - Never include secrets (API keys, credentials, tokens). - Max 10 files in KEY FILES. GOAL is one sentence. ## Continuation Instructions For chat output, tell the user: ```plaintext TO CONTINUE IN A NEW SESSION: 1. Run /clear (or start a fresh `claude` session / new terminal). 2. Paste the HANDOFF CONTEXT above as your first message. 3. Add: "Continue from the handoff context above. [your next task]" ``` ## Common Mistakes - Writing a file from this skill without one of the File Mode triggers: an explicit request or a context-threshold nudge. - Putting an instruction for the receiving session only in this skill; the receiver reads the handoff, so anything it must do belongs in the handoff text. - Committing a handoff file. - Paraphrasing user requests or inventing constraints — both must be verbatim. - Using `#` headers / bold / code fences in the content — breaks clean paste. - Calling non-existent tools (`session_read`, `todoread`) — the conversation is already in context. - Dropping the fixed re-read line from CONTEXT FOR CONTINUATION: without it the receiving side builds on stated status (tracker, review, store or console, inbox) that may have changed since the handoff was written.