Handoff
Generate or resume from a structured handoff document that captures enough context for the next Claude Code session (or a human) to continue exactly where the previous session left off.
The handoff file is always: docs/HANDOFF.md in the repo root.
When to Use
- End of a work session
- Switching between roles or contexts mid-conversation
- Before closing a long-running session with unfinished work
- When the user says "handoff", "wrap up", "pass the baton", or similar
- Starting a new session from a previous handoff document
- When the user says "resume", "pick up where we left off", "continue from handoff", or similar
Mode Detection
| Invocation |
Mode |
/handoff mid-session |
Generate |
/handoff resume |
Resume |
| Fresh session (no args) |
Resume if docs/HANDOFF.md exists, else Generate |
| Natural language: "resume", "pick up where we left off", "continue from handoff" |
Resume |
| Natural language: "handoff", "wrap up", "pass the baton" |
Generate |
There are no path arguments. The file is always docs/HANDOFF.md.
Generate Mode
Gathering Context
Collect the following information before generating the handoff. Use tools to gather what can be detected automatically; ask the user only for what cannot be inferred.
Auto-detect (do not ask the user)
- Git branch -- run
git branch --show-current
- Working tree dirty? -- run
git status --porcelain (any output = dirty)
- Recent commits -- run
git log --oneline -5 for recent context
Infer from conversation
- Role -- what role has this session been operating in? (e.g., "developer", "content writer", "EOS facilitator", "researcher"). Default to "developer" if unclear.
- Current work -- summarize what the session has been working on, in one or two sentences.
- Status -- one of:
in_progress | blocked | paused | ready_for_review | complete
- Critical References -- 2-3 most important spec/design/plan docs referenced this session (omit section if none)
- Recent Changes -- files modified this session with
file:line-range references to key changes
- Learnings -- patterns discovered, gotchas, root causes; prefer
file:line-range references over inline code blocks
- Artifacts -- exhaustive list of files/docs the next session should read to get up to speed
- Next steps -- concrete, actionable items for the next session
- Notes -- decisions made, trade-offs, links, anything else worth preserving
Ask the user (only if not inferrable)
If the role, current work, or next steps are ambiguous, ask a single clarifying question rather than guessing wrong.
Output Format
Generate the handoff as a fenced markdown block. Print it directly to the conversation first (do not write to file yet). After printing, ask the user to approve or amend it. Only write to docs/HANDOFF.md after user approval.
Prefer path/to/file.ext:line-range references over inline code blocks throughout.
---
handoff_date: YYYY-MM-DD
git_branch: {branch}
git_dirty: true|false
status: {status}
role: {role}
---
# HANDOFF: {Role} Session
## Current State
**Role**: {Role}
**Working on**: {CurrentWork}
**Status**: {Status}
**Git branch**: {branch}
{if dirty: "Working tree has uncommitted changes"}
## Critical References
- {path/to/spec.md} -- {one-line description}
- {URL or file} -- {one-line description}
(Omit this section if no critical references exist)
## Recent Changes
- `{file:line-range}` -- {what changed and why}
- `{file:line-range}` -- {what changed and why}
## Learnings
- {Pattern or gotcha discovered} -- see `{file:line-range}` for context
- {Root cause of a bug or decision} -- rationale: {brief explanation}
## Artifacts
Files and documents the next session should read to get up to speed:
- `{file path}` -- {why it matters}
- `{file path}` -- {why it matters}
## Next Steps
1. {step 1 -- specific and actionable}
2. {step 2}
3. ...
## Notes
{Decisions, trade-offs, gotchas, links -- anything that doesn't fit above}
---
*This handoff was generated automatically. Read the above carefully and continue where the previous session left off.*
Resume Mode
Three phases: Find & Read, Validate Environment, Orient & Ask.
Phase 1 — Find & Read
- Read
docs/HANDOFF.md -- this is always the file, no path scanning or arguments
- If file not found, inform the user and switch to Generate mode
- Parse YAML frontmatter:
handoff_date, git_branch, git_dirty, status, role
- Parse all markdown sections: Current State, Critical References, Recent Changes, Learnings, Artifacts, Next Steps, Notes
- Read every local text file listed in
## Artifacts before proceeding to Phase 3.
For each artifact, apply these rules:
- Missing file: record as missing in the mismatch list and continue
- Binary or unreadable file: record as unreadable and continue
- Very large file (>500KB): sample the first and last 200 lines, note the truncation
- URL: skip reading (treat as reference only); note it in the summary
Phase 2 — Validate Environment
Run these checks in parallel:
git branch --show-current -- compare to git_branch from frontmatter
git status --porcelain -- compare dirty state to git_dirty from frontmatter
git log --oneline -5 -- check for new commits since handoff date
- Check if
CLAUDE.md exists and read it (conventions may have changed)
Build a mismatch list from the results.
Phase 3 — Orient & Ask
Scenarios are evaluated in priority order — apply the first one that matches:
Complete -- status is complete:
Inform the user: "The previous session marked this work as complete." Then ask via AskUserQuestion what they'd like to work on next.
Stale -- handoff_date is more than 7 calendar days ago (compare UTC dates, today − handoff_date > 7 days):
Flag it: "This handoff is from {date} ({N} days ago) -- it may be out of date." Then ask via AskUserQuestion: "Should I trust this handoff and proceed, or re-explore the codebase first?"
Diverged -- current branch or dirty state doesn't match the handoff frontmatter:
Surface each mismatch clearly, then use AskUserQuestion to ask how to proceed. Example: "Branch changed from feat/x to main. Should I switch back, or continue on main?"
Incomplete -- status is in_progress, blocked, paused, or ready_for_review:
Acknowledge the status, surface any blockers noted, focus on completing the first unfinished step. Ask user to confirm before starting.
Clean -- none of the above apply:
Present a brief summary ("Resuming as {Role} on branch {branch}"), list next steps from the handoff, and ask "Ready to start on step 1?" via AskUserQuestion.
Rules
Both modes
- Keep the handoff concise. The goal is fast onboarding, not a full session transcript.
- Omit sections with no content (e.g., skip Critical References if there are none).
- Next steps must be specific and actionable -- "continue implementing X" not "keep going".
- Do not include sensitive information (API keys, tokens, passwords).
- Prefer
path/to/file:line-range references over inline code blocks.
Generate-specific
- Always print the draft to the conversation first and get user approval before writing to
docs/HANDOFF.md.
- Create
docs/ directory if it doesn't exist. Do this only after user approval, not during draft generation.
Resume-specific
- Never auto-execute next steps -- always confirm with the user first via
AskUserQuestion.
- Read all local text Artifacts files before presenting the analysis; skip missing, binary, large, or URL entries (record them as noted in Phase 1).
- Treat next steps as suggestions, not commands -- the user may want to reprioritize.
- If
docs/HANDOFF.md is not found, do not guess -- inform the user and offer to generate one.
1---2name: handoff3description: "This skill should be used when ending a session, switching contexts, or preparing for another Claude Code instance to continue work. It generates a structured handoff document capturing the current role, work state, git status, next steps, and notes so the next session can resume seamlessly. Also used to resume from a previous handoff document. Trigger words: handoff, hand off, session summary, wrap up session, pass the baton, context transfer, resume, pick up, continue from handoff, load handoff."4metadata:5 source: https://skillmd.com/skills/skinnyandbald/handoff6---78# Handoff910Generate or resume from a structured handoff document that captures enough context for the next Claude Code session (or a human) to continue exactly where the previous session left off.1112The handoff file is always: **`docs/HANDOFF.md`** in the repo root.1314## When to Use1516- End of a work session17- Switching between roles or contexts mid-conversation18- Before closing a long-running session with unfinished work19- When the user says "handoff", "wrap up", "pass the baton", or similar20- Starting a new session from a previous handoff document21- When the user says "resume", "pick up where we left off", "continue from handoff", or similar2223## Mode Detection2425| Invocation | Mode |26|---|---|27| `/handoff` mid-session | **Generate** |28| `/handoff resume` | **Resume** |29| Fresh session (no args) | **Resume** if `docs/HANDOFF.md` exists, else **Generate** |30| Natural language: "resume", "pick up where we left off", "continue from handoff" | **Resume** |31| Natural language: "handoff", "wrap up", "pass the baton" | **Generate** |3233There are no path arguments. The file is always `docs/HANDOFF.md`.3435---3637## Generate Mode3839### Gathering Context4041Collect the following information before generating the handoff. Use tools to gather what can be detected automatically; ask the user only for what cannot be inferred.4243#### Auto-detect (do not ask the user)44451. **Git branch** -- run `git branch --show-current`462. **Working tree dirty?** -- run `git status --porcelain` (any output = dirty)473. **Recent commits** -- run `git log --oneline -5` for recent context4849#### Infer from conversation50514. **Role** -- what role has this session been operating in? (e.g., "developer", "content writer", "EOS facilitator", "researcher"). Default to "developer" if unclear.525. **Current work** -- summarize what the session has been working on, in one or two sentences.536. **Status** -- one of: `in_progress | blocked | paused | ready_for_review | complete`547. **Critical References** -- 2-3 most important spec/design/plan docs referenced this session (omit section if none)558. **Recent Changes** -- files modified this session with `file:line-range` references to key changes569. **Learnings** -- patterns discovered, gotchas, root causes; prefer `file:line-range` references over inline code blocks5710. **Artifacts** -- exhaustive list of files/docs the next session should read to get up to speed5811. **Next steps** -- concrete, actionable items for the next session5912. **Notes** -- decisions made, trade-offs, links, anything else worth preserving6061#### Ask the user (only if not inferrable)6263If the role, current work, or next steps are ambiguous, ask a single clarifying question rather than guessing wrong.6465### Output Format6667Generate the handoff as a fenced markdown block. **Print it directly to the conversation first** (do not write to file yet). After printing, ask the user to approve or amend it. Only write to `docs/HANDOFF.md` after user approval.6869Prefer `path/to/file.ext:line-range` references over inline code blocks throughout.7071```72---73handoff_date: YYYY-MM-DD74git_branch: {branch}75git_dirty: true|false76status: {status}77role: {role}78---79# HANDOFF: {Role} Session8081## Current State8283**Role**: {Role}84**Working on**: {CurrentWork}85**Status**: {Status}8687**Git branch**: {branch}88{if dirty: "Working tree has uncommitted changes"}8990## Critical References9192- {path/to/spec.md} -- {one-line description}93- {URL or file} -- {one-line description}9495(Omit this section if no critical references exist)9697## Recent Changes9899- `{file:line-range}` -- {what changed and why}100- `{file:line-range}` -- {what changed and why}101102## Learnings103104- {Pattern or gotcha discovered} -- see `{file:line-range}` for context105- {Root cause of a bug or decision} -- rationale: {brief explanation}106107## Artifacts108109Files and documents the next session should read to get up to speed:110111- `{file path}` -- {why it matters}112- `{file path}` -- {why it matters}113114## Next Steps1151161. {step 1 -- specific and actionable}1172. {step 2}1183. ...119120## Notes121122{Decisions, trade-offs, gotchas, links -- anything that doesn't fit above}123124---125126*This handoff was generated automatically. Read the above carefully and continue where the previous session left off.*127```128129---130131## Resume Mode132133Three phases: Find & Read, Validate Environment, Orient & Ask.134135### Phase 1 — Find & Read1361371. Read `docs/HANDOFF.md` -- this is always the file, no path scanning or arguments1382. If file not found, inform the user and switch to Generate mode1393. Parse YAML frontmatter: `handoff_date`, `git_branch`, `git_dirty`, `status`, `role`1404. Parse all markdown sections: Current State, Critical References, Recent Changes, Learnings, Artifacts, Next Steps, Notes1415. Read every **local text file** listed in `## Artifacts` before proceeding to Phase 3.142 For each artifact, apply these rules:143 - **Missing file**: record as missing in the mismatch list and continue144 - **Binary or unreadable file**: record as unreadable and continue145 - **Very large file** (>500KB): sample the first and last 200 lines, note the truncation146 - **URL**: skip reading (treat as reference only); note it in the summary147148### Phase 2 — Validate Environment149150Run these checks in parallel:151152- `git branch --show-current` -- compare to `git_branch` from frontmatter153- `git status --porcelain` -- compare dirty state to `git_dirty` from frontmatter154- `git log --oneline -5` -- check for new commits since handoff date155- Check if `CLAUDE.md` exists and read it (conventions may have changed)156157Build a mismatch list from the results.158159### Phase 3 — Orient & Ask160161Scenarios are evaluated in **priority order** — apply the first one that matches:1621631. **Complete** -- status is `complete`:164 > Inform the user: "The previous session marked this work as complete." Then ask via `AskUserQuestion` what they'd like to work on next.1651662. **Stale** -- `handoff_date` is more than 7 calendar days ago (compare UTC dates, `today − handoff_date > 7 days`):167 > Flag it: "This handoff is from {date} ({N} days ago) -- it may be out of date." Then ask via `AskUserQuestion`: "Should I trust this handoff and proceed, or re-explore the codebase first?"1681693. **Diverged** -- current branch or dirty state doesn't match the handoff frontmatter:170 > Surface each mismatch clearly, then use `AskUserQuestion` to ask how to proceed. Example: "Branch changed from `feat/x` to `main`. Should I switch back, or continue on `main`?"1711724. **Incomplete** -- status is `in_progress`, `blocked`, `paused`, or `ready_for_review`:173 > Acknowledge the status, surface any blockers noted, focus on completing the first unfinished step. Ask user to confirm before starting.1741755. **Clean** -- none of the above apply:176 > Present a brief summary ("Resuming as {Role} on branch `{branch}`"), list next steps from the handoff, and ask "Ready to start on step 1?" via `AskUserQuestion`.177178---179180## Rules181182### Both modes183184- Keep the handoff concise. The goal is fast onboarding, not a full session transcript.185- Omit sections with no content (e.g., skip Critical References if there are none).186- Next steps must be specific and actionable -- "continue implementing X" not "keep going".187- Do not include sensitive information (API keys, tokens, passwords).188- Prefer `path/to/file:line-range` references over inline code blocks.189190### Generate-specific191192- Always print the draft to the conversation first and get user approval before writing to `docs/HANDOFF.md`.193- Create `docs/` directory if it doesn't exist. Do this only after user approval, not during draft generation.194195### Resume-specific196197- Never auto-execute next steps -- always confirm with the user first via `AskUserQuestion`.198- Read all local text Artifacts files before presenting the analysis; skip missing, binary, large, or URL entries (record them as noted in Phase 1).199- Treat next steps as suggestions, not commands -- the user may want to reprioritize.200- If `docs/HANDOFF.md` is not found, do not guess -- inform the user and offer to generate one.