handing-off-session

Session Handoff

Target: $ARGUMENTS

Captures session state as a structured markdown note for the next session to pick up. Stateless — markdown files only, no database, no daemon.

Arguments

Position	Name	Required	Default	Description
1	output-path	no	auto	Where to write the handoff note.

Default output path: .claude/handoffs/YYYY-MM-DD-<short-description>.md

The <short-description> is a 2-4 word slug derived from the session's primary focus (e.g. 2026-04-06-session-handoff-skill.md).

When to Use

• End of a work session
• Switching context to a different project or task
• Before a long break
• When context window is getting full and you want to preserve state

Workflow

1. Scan conversation — Identify completed actions, decisions, and pending work from the current session context.

2. Check git state — Run git diff --stat and git log --oneline -10 to capture recent changes and commits.

3. Extract signals — Collect decisions made, alternatives rejected, blockers encountered, and open questions.

4. Ensure output dir — Create .claude/handoffs/ if it doesn't exist.

5. Write handoff note — Use the template below. Be concise — enough to resume, no more.

Output Template

# Session Handoff — <date>

## What Was Done
[Completed work, key commits, PRs created/merged]

## What's Pending
[Open tasks, unfinished work, next steps]

## Key Decisions
[Architectural choices, trade-offs made, rejected alternatives]

## Modified Files
[List of files changed with brief reason]

## Blockers
[External dependencies, open questions, things that need user input]

Picking Up a Handoff

Next session can read the latest handoff:

# Find latest handoff
ls -t .claude/handoffs/*.md | head -1

Or read all recent handoffs to rebuild context across multiple sessions.

Quality Check

• Correct > Complete > Minimal (ACE-FCA)
• ~20-50 lines output per handoff
• Every item traces to a concrete action or artifact
• No raw dumps — structured summaries only