| name | handoff |
| description | Session continuity — save structured task state so the next conversation picks up where you left off. TRIGGER when the user says /handoff, "save progress", "let's pause here", "wrap up", or is ending a complex multi-step session. Also trigger when resuming: "pick up where I left off", "check handoffs", "what was I working on". |
| allowed-tools | Read, Write, Edit, Glob, Grep, Bash |
| argument-hint | [{"optional":"topic name or \"resume\""}] |
Handoff — Session Continuity
You manage session continuity by saving and restoring structured task state across conversations.
ultrathink
Two Modes
This skill operates in one of two modes based on context:
Mode 1: SAVE (default)
Trigger: user says /handoff, "save progress", "let's pause here", or the session is ending after complex work.
Mode 2: RESUME
Trigger: user says /handoff resume, "pick up where I left off", "check handoffs", "what was I working on", or starts a session in a project that has recent handoff files.
Mode 1: SAVE — Capture Session State
Step 1: Gather Context
Scan the current conversation to extract:
- Objective — What were we trying to accomplish? State the goal clearly.
- Progress — What's done? List completed work with specific file paths and line numbers.
- Current state — Where exactly did we stop? What was the last thing done or being worked on?
- Files modified — Every file touched in this session, with a brief note on what changed.
- Pending work — What remains? List as checkboxes.
- Key decisions — Decisions made during the session with their rationale. These are the easiest things to lose.
- Blockers / Open questions — Anything unresolved that the next session needs to address.
- How to resume — Concrete instructions for picking up: which file to open, which test to run, what to do next.
Also check:
git status and git diff --stat for uncommitted changes
git log --oneline -5 for recent commits made in this session
- Any running background tasks or pending agent results
Step 2: Determine Handoff Location
Resolve the project memory directory:
- Determine the current working directory
- Map it to the Claude Code project memory path:
~/.claude/projects/<encoded-path>/memory/
- Create
handoffs/ subdirectory if it doesn't exist
- File name:
handoffs/YYYY-MM-DD-<topic-slug>.md
If the topic is unclear, derive it from the objective (e.g., "auth-middleware-refactor", "thesis-chapter-5-revision").
Step 3: Write the Handoff File
Write the handoff file with this exact structure:
---
date: YYYY-MM-DD
topic: <topic>
project: <absolute project path>
status: active
---
# Handoff: <Topic>
## Objective
<Clear statement of what we were trying to accomplish>
## Progress
- [x] Completed item 1 (file: path/to/file.ts, lines 10-50)
- [x] Completed item 2
## Current State
<Exact point of interruption — what was the last thing done>
## Uncommitted Changes
<Output of git status / git diff --stat, or "None — all changes committed">
## Files Modified
- `path/to/file1.ts` — Description of changes
- `path/to/file2.ts` — Description of changes
## Pending Work
- [ ] Remaining task 1
- [ ] Remaining task 2
- [ ] Remaining task 3
## Key Decisions
- Decision 1 — Rationale: why we chose this approach
- Decision 2 — Rationale: why we chose this approach
## Blockers / Open Questions
- Question or blocker that needs resolution
## How to Resume
1. Open <file> and look at <location>
2. Run <command> to verify current state
3. Next step: <specific action to take>
Step 4: Update Memory Indexes
-
Project-local MEMORY.md — Add a one-line entry:
- [Handoff: <topic>](handoffs/YYYY-MM-DD-<slug>.md) — <one-line summary of state>
-
Daily log — Append to memory/daily/YYYY-MM-DD.md:
- HH:MM — Handoff saved: <topic>. Status: <brief state>.
-
Mark previous handoffs as superseded — If there's an older handoff for the same topic, update its status frontmatter from active to superseded.
Step 5: Confirm to User
Show a brief summary:
- Handoff file location
- Objective captured
- Number of pending items
- How to resume next time ("Start a new session and say 'pick up where I left off' or '/handoff resume'")
Mode 2: RESUME — Restore Session State
Step 1: Find Handoff Files
- Determine the current project memory directory
- Look for
handoffs/ subdirectory
- List all handoff files, sorted by date (newest first)
- Filter to
status: active only (ignore superseded)
If no handoffs exist, tell the user and offer to check other projects:
- Read MEMORY.md indexes from
~/.claude/projects/*/memory/MEMORY.md
- Look for handoff entries across all projects
- Present any found, noting which project they belong to
Step 2: Present Handoff(s)
If one active handoff: read and present it directly.
If multiple active handoffs: show a brief list and ask which to resume.
Present the handoff as a briefing:
## Resuming: <Topic>
**Last session:** <date>
**Objective:** <objective>
**Where we left off:** <current state>
**Pending work:** <N items remaining>
Step 3: Verify Current State
Before diving in, verify the handoff is still accurate:
- Check if the files mentioned still exist and match expectations
- Run
git status to see if there are changes since the handoff
- Check
git log --oneline -5 for commits since the handoff date
- If state has changed (someone else worked on it, or the user made manual changes), note the differences
Step 4: Reconstruct Context
Read the key files mentioned in the handoff to rebuild working context:
- Open files listed in "Files Modified"
- Check the specific lines/locations mentioned in "How to Resume"
- Load any relevant daily logs since the handoff date
Present a "ready to go" summary:
## Ready to Resume
- State verified: <matches handoff / has diverged>
- Next step: <from "How to Resume">
- Pending: <checkbox list from handoff>
Ask the user to confirm before proceeding with the pending work.
Edge Cases
- No complex work to hand off: If the session was simple Q&A with no task state, say so. Don't create an empty handoff.
- Multiple topics in one session: Create separate handoff files for each distinct topic.
- Handoff during multi-agent work: Note which agents were running and their last known state.
- Stale handoffs: If a handoff is older than 2 weeks and its objective seems completed (based on git history), suggest archiving it.
User's Input
$ARGUMENTS