# Handoff

> 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".

- Skill: `andrehuang-claude-claw/handoff` (Agent Skill)
- Install (CLI): `npx skillmds@latest add andrehuang-claude-claw/handoff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/andrehuang-claude-claw/handoff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: andrehuang (https://skillmd.com/u/andrehuang-claude-claw)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/andrehuang-claude-claw/handoff

---


# 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:

1. **Objective** — What were we trying to accomplish? State the goal clearly.
2. **Progress** — What's done? List completed work with specific file paths and line numbers.
3. **Current state** — Where exactly did we stop? What was the last thing done or being worked on?
4. **Files modified** — Every file touched in this session, with a brief note on what changed.
5. **Pending work** — What remains? List as checkboxes.
6. **Key decisions** — Decisions made during the session with their rationale. These are the easiest things to lose.
7. **Blockers / Open questions** — Anything unresolved that the next session needs to address.
8. **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:

1. Determine the current working directory
2. Map it to the Claude Code project memory path: `~/.claude/projects/<encoded-path>/memory/`
3. Create `handoffs/` subdirectory if it doesn't exist
4. 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:

```markdown
---
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

1. **Project-local MEMORY.md** — Add a one-line entry:
   `- [Handoff: <topic>](handoffs/YYYY-MM-DD-<slug>.md) — <one-line summary of state>`

2. **Daily log** — Append to `memory/daily/YYYY-MM-DD.md`:
   `- HH:MM — Handoff saved: <topic>. Status: <brief state>.`

3. **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

1. Determine the current project memory directory
2. Look for `handoffs/` subdirectory
3. List all handoff files, sorted by date (newest first)
4. 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:

1. Check if the files mentioned still exist and match expectations
2. Run `git status` to see if there are changes since the handoff
3. Check `git log --oneline -5` for commits since the handoff date
4. 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