| name | handoff |
| description | Create a structured handoff document for seamless continuity across Claude conversations. Use when the user explicitly asks to create a handoff, handover, or session transfer document, or signals they want to stop now and continue this work in a future conversation. Trigger phrases include: "create a handoff", "handoff document", "handover", "save session", "continue later", "session handoff", "transfer context", "let's pick this up tomorrow", "save this so we can continue next time", or "/handoff". Do NOT trigger for general conversation summaries, meeting notes, or when the user simply asks "summarise this conversation" without handoff/continuity intent. Do NOT trigger when the user uploads an existing handoff document to resume from — handoff documents are self-contained and carry their own resumption instructions; this skill is for creating them only.
|
Session Handoff Skill
Create a structured markdown document that enables a fresh Claude conversation to continue the current task seamlessly. The handoff captures working state — goals, progress, decisions, context, and next steps — so the receiving session picks up exactly where this one left off.
When to Use
- The user explicitly requests a handoff or handover document
- The user signals they are stopping now and want to continue the work in a later conversation
- Before ending a long or complex conversation with unfinished work
- When approaching context limits and needing to start fresh
Not for resuming. If the user has uploaded a handoff document and wants to continue from it, the document itself contains everything needed — follow its embedded resumption instruction and do not use this skill.
Process
Step 1: Analyse the Session
Silently assess:
- Work type — Which category fits? (see Work Type Classification)
- Complexity tier — How deep is the work? (see Depth Sizing)
- Active state — What is the current task, and where exactly did we stop?
- Accumulated context — What knowledge, constraints, and decisions were established that would be costly to re-establish?
Step 2: Check for User Instructions
If the user included specific instructions in their handoff request (e.g. "create a handoff, make sure to include X", or a stated direction for the next session), incorporate those.
Step 3: Clarify Ambiguities (Conditional)
Skip this step entirely if the session state is clear. Ask at most 2-3 short, specific questions only when a genuine ambiguity would produce a materially different handoff:
- Scope — The session covered multiple distinct topics and it is unclear which the handoff should cover.
- Decision status — Something was discussed at length but not clearly resolved. Unclear whether to record it as settled or open.
- Priority / direction — Ask only when the conversation suggests the user already has a preferred next direction that was left unstated, and the ordering would materially change the handoff. An undecided direction is a valid end state, not an ambiguity. If the user simply has not chosen what to work on next, do not ask — record it (see Possible Directions below).
Do not ask: open-ended questions ("anything specific you want me to capture?", "what do you want to work on next?"), questions answered or implied in the conversation, or questions about minor details that would not change the handoff's usefulness.
Step 4: Generate the Handoff Document
Build the document using the adaptive structure matching the work type and complexity tier.
Step 5: Output
Save as a markdown file and present it for download.
Filename: YYYY-MM-DD-handoff-[brief-description].md
Use today's date and a short descriptive slug (e.g. 2026-06-11-handoff-epq-silicon-anode-research.md). The date prefix keeps multiple handoffs sortable and prevents collisions.
Work Type Classification
Classify the session to determine which structural sections are most relevant. If a session spans multiple types, use the primary type and pull in sections from secondary types.
Research / Investigation
Exploring a topic, gathering sources, evaluating information, forming conclusions.
Key sections: Objective, Findings So Far, Sources and Evidence, Open Questions, Methodology, Conclusions Reached, Gaps Remaining.
Writing / Drafting
Producing or editing text: essays, applications, emails, articles, documentation.
Key sections: Objective, Current Draft State, Tone and Style Decisions, Structural Outline, Content Completed vs Remaining, Editorial Decisions.
Planning / Strategy
Designing plans, making decisions, evaluating options, setting direction.
Key sections: Objective, Options Considered, Decisions Made (with rationale), Constraints, Current Plan State, Unresolved Questions, Dependencies.
Building / Technical
Creating something: websites, apps, designs, configurations, data work.
Key sections: Objective, Architecture/Structure Decisions, What Has Been Built, Technical Choices (with rationale), File and Asset References, Issues Encountered, Remaining Implementation.
Learning / Exploration
Understanding a concept, working through problems, studying material.
Key sections: Objective, Concepts Covered, Key Takeaways, Areas of Confusion Remaining, Resources Used, Topics Still to Cover.
Problem-Solving / Debugging
Diagnosing an issue, troubleshooting, iterating toward a solution.
Key sections: Objective, Problem Description, Hypotheses Tested, What Worked / What Did Not, Current Diagnosis, Remaining Approaches to Try.
Mixed / General
Use the universal structure and pull in type-specific sections as needed.
Depth Sizing
Size the handoff to the complexity of the work. Be complete on decisions, rationale, and failed approaches; ruthless on everything else. The receiving session pays to read every word, and an overlong handoff buries the next-step signal. The handoff fails only if the user has to re-explain something — not if it omits things Claude already knows.
- Light (roughly 300–600 words) — Simple, focused tasks nearing completion. One clear objective, few decisions, minimal accumulated context.
- Standard (roughly 600–1200 words) — Moderate tasks with meaningful progress and several decisions. Some context that would take effort to rebuild.
- Deep (roughly 1200–2500 words) — Complex, multi-faceted work: many decisions, established constraints, domain knowledge built up during the session, or long iterative work.
- Extended (roughly 2500+ words) — Use sparingly. For sessions where the conversation itself has been the workspace: large decision chains or multiple interconnected workstreams.
These counts are calibration guidelines, not targets to fill.
Handoff Document Structure
Every handoff follows this skeleton. Include or exclude sections based on work type and relevance. Never include empty sections.
# Handoff: [Descriptive Title]
> **Resumption instruction:** Review this document, then confirm your
> understanding in 2–3 sentences before proceeding with the next step.
> This document is self-contained — do not consult or load the handoff
> skill; it is for creating handoffs, not resuming from them.
**Date:** [YYYY-MM-DD]
**Work type:** [Research / Writing / Planning / Building / Learning / Problem-Solving / Mixed]
**Status:** [In Progress / Paused / Nearing Completion / Blocked]
---
## Objective
[What we are trying to accomplish and why. The north star for the receiving
session — enough context to understand motivation and scope, not just the task.]
## Current State
[A precise snapshot of where the work stands right now — not a summary of the
conversation. Not "we discussed the layout" but "the layout is finalised as a
two-column grid with sidebar navigation; the header is built, the footer is not."]
## Progress
[Concrete outputs and milestones accomplished this session. Concise entries,
not narrative.]
## Decisions Made
[Each decision with its rationale. The rationale prevents the new session from
relitigating settled questions or unknowingly reversing a considered choice.]
- **[Decision]** — [Why this was chosen over alternatives]
## Approaches That Did Not Work
[Directions tried and rejected, with reasons. Prevents the most common failure
mode: the new session re-exploring dead ends.]
## Project Context
[Stable background: constraints, preferences, and domain knowledge established
during the session that does not change between sessions. Only include when
there is meaningful context beyond the objective. Do not duplicate information
already in Claude's memory system.]
## Open Questions
- [ ] [Specific question needing resolution — not a vague area]
## Next Steps
[Ordered and immediately actionable. The first item is the very next thing to
do. Mark any step only the user can perform with **(user)** — the receiving
session should prompt for these, not attempt them.]
1. [First action — specific and concrete]
2. **(user)** [Action the user must perform, e.g. reviewing output, publishing]
## Possible Directions
[Use INSTEAD of Next Steps when the user has deliberately not chosen what to
work on next. State "Direction undecided" and list the candidate directions as
options with a one-line case for each. The receiving session should present
these as choices, not pick one and proceed.]
- **[Candidate direction]** — [Why it might be next]
## Key References
[Links, file names, or sources relevant to continuing. Every artifact produced
in this session (scripts, files, documents) must be referenced by a retrievable
location — a path, URL, or repo — or explicitly marked as not preserved. A
reference the receiving session cannot retrieve is not a reference.]
Content Guidelines
Include:
- Tone, style, or voice decisions explicitly established during writing tasks
- Agreed structural outlines or plans that guide remaining work
- Technical specifics (exact values, configurations) that would be hard to rediscover
- Source evaluations for research tasks: which sources proved useful and which did not
Exclude:
- Conversational narrative — capture state, not history
- General knowledge — "We discussed how spaced repetition works" adds nothing. "Decided on 2-day initial intervals to fit the revision schedule" adds value
- Intermediate reasoning — capture conclusions and rationale, not every step
- Verbose tool output — summarise or reference, never reproduce
- Pleasantries and meta-discussion
Quality Checklist
Before outputting, verify:
