Handoff — Session Handoff Skill for Claude Code
Generates structured session handoffs before context runs out, chain-linking across sessions so the next one never re-discovers what was already tried.
Transparent behavior: local file writes and git reads only; optional external deps (beads/OpenViking) are skipped when absent; commit is confirmed with the user and a 'close without commit' path exists; archiving moves rather than deletes. Deducted for: the close-session flow defaults to staging and committing all session-related files, so least-privilege and confirmation are incomplete; publisher identity unverified.
Instructions are internally consistent with explicit degradation paths (skip bd if unavailable, ask on ambiguous chains, default to new chain). Deducted for: static review cannot execute key paths (chain detection grep, two-phase write, self-validation); no test evidence; the deep/chunked protocols depend on model self-discipline, limiting determinism.
Triggers are explicit and clear, non-fit cases are declared (plan mode, discussions, ambiguous requests prompt first), and the target scenario (long-session context handoff) is well defined. Deducted for: strong coupling to Claude Code and English conventions; boundary behavior in non-git or no-tracker environments is not fully specified; no Chinese-language support statement (core function does not depend on unreachable services, so deduction is limited).
Good layered documentation: main SKILL.md plus references (template, validation, mining protocol, close flow); README covers install/uninstall; clear MIT license. Deducted for: no version/changelog inside the skill files, no declared maintenance ownership or update path, incomplete known-limitations disclosure.
The structured handoff file and ready-to-paste resume prompt are directly usable outputs; the template is comprehensive and the marginal-value claim (less rediscovery) is plausible. Deducted for: static review cannot verify output quality; the README's A/B testing claims are author assertions without raw data; mandatory line minimums (150-800) may produce bloated output with unverified cost/benefit.
Source files are auditable primary material, and a third-party study ('lost in the middle') is cited without a link. Deducted for: A/B test claims are not reproducible, no test suite or CI covering key paths, and fact/inference separation is weak (e.g., unsourced '20-40% waste' figures); low static-only score.
- Default commit behavior: answering 'Yes' in close-session stages and commits session-related files; unrelated changes could be committed if file review is rushed — prefer 'close without commit' or verify the file list.
- README A/B testing comparisons and the 20-40% efficiency claim are author assertions without independent verification.
- beads and OpenViking are optional; absence degrades functionality (no chain tag, no memory persistence). No version numbers or changelog inside the skill files.
- Mandatory line minimums (150-800) can yield bloated handoff files disproportionate to short sessions.
- Publisher identity is unverified; this is a static source review — no skill path was executed.
What does this skill do, and when should you use it?
Handoff is a Claude Code skill that fires when context is running low (typically ~75%) or work is pausing. It deep-mines the entire conversation, gathers git state in parallel, detects prior handoffs in the same work stream via chain tags and sequence numbers, adapts its mining strategy to context size, and self-validates its output before finishing. The result is a long, structured Markdown file plus a ready-to-paste resume prompt for a fresh session. Files land in plans/handoffs/ or .claude/handoffs/, with optional Beads issue-tracker integration.
Runs git log/diff/status/branch and lists existing handoff directories in parallel; detects the parent handoff via Tier A (pasted-prompt, deterministic) or Tier B (bead grep, heuristic) matching and inherits chain tag + seq; launches parallel context agents for prior decisions, reference docs, and stale-identifier checks; runs a Quick, Deep, or Chunked conversation-mining pass based on context size using a 12-item extraction checklist (goals, approaches tried, failures and why, measurements, decisions, user preferences); writes the handoff in a two-phase process within a line budget (300-400 lines standard, 500-800 on 1M context); self-validates against references/validation.md; optionally updates Beads via bd update/remember; reports the file path, chain info, and Next Action, then asks whether to close the session and emits a paste prompt. Completed chains archive to plans/handoffs/archive/.
- A developer near the context ceiling mid-session who wants full progress captured instead of relying on Claude's auto-compaction summary
- An engineer returning across multiple days to the same bug fix, wanting session three to inherit the chain from sessions one and two
- Teams using Beads or another CLI task tracker who want handoffs automatically tagged to active issues
- Heavy Claude Code users losing 20-40% of each session rediscovering already-tried failed approaches
- Users of 1M-context windows with hundreds of thousands of tokens of history needing chunked map-reduce mining
What are this skill's strengths and limitations?
- Chain tracking (chain tag + sequence) lets session N inherit all prior session context
- Two-phase write with self-validation and enforced line minimums prevents thin, useless handoffs
- Explicitly prioritizes failed approaches — the most expensive context to rediscover
- Guards against misuse: refuses plan mode, ambiguous requests, and freeform generation
- Context-size adaptive: switches to multi-pass map-reduce mining at 500K+ tokens
- MIT licensed; pairs with Beads, OpenViking, Git, and any CLI task tracker
- Depends on Claude Code-specific features (triggers, $ARGUMENTS, slash commands); porting to other clients requires edits
- Handoff files are long (hundreds of lines) — a real cost on small-context clients
- Beads (bd CLI) and OpenViking integrations are optional; features degrade without them
- The A/B testing claims in the README are author-reported, with no independent verification or test suite
- Tier B parent detection is heuristic and requires user confirmation in ambiguous cases
How do you install this skill?
git clone https://github.com/REMvisual/claude-handoff.git, then cp -r claude-handoff/skills/handoff ~/.claude/skills/ (the repo also bundles the handoffplan skill if you want both). Verify by typing /handoff in Claude Code — it should appear in autocomplete. Optional PreCompact hook: copy hooks/precompact-handoff.sh to ~/.claude/hooks/ and chmod +x. Adding an anti-shadowing rule to your CLAUDE.md is recommended so Claude never generates freeform handoff summaries.
How do you use this skill?
Just type /handoff — no arguments required (optional reasons like "context low" or "end of day" are accepted as soft hints). Triggers include 'do a handoff', 'running out of context', 'save session progress'. When done, the skill prints a paste prompt like 'Read plans/handoffs/HANDOFF_xxx.md (seq 2, chain-x) and continue' — paste it into a fresh Claude Code session to resume.
How does this skill compare with similar options?
The README contrasts it with Claude's built-in compaction summaries: those lack chain tracking, self-validation, and evidence mining. In author-run A/B tests (same bug, same codebase, fresh sessions), the skill-based session needed zero user intervention and traced the complete failure call chain, while the unstructured one needed a human correction and proposed only a surface-level fix. The sibling skill in the same repo, handoffplan, differs: /handoff is for pausing exploration (next session onboards and explores), while /handoffplan adds a phased execution plan for when research is done — this profile covers /handoff only.