Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Other skills

handoff

Create a structured session handoff when context is running low or work is pausing. Deep context mining, self-validation, multi-file splitting. Captures everything the next session needs.

REMvisual · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add REMvisual/claude-handoff --skill handoff

About this skill


name: handoff description: Create a structured session handoff when context is running low or work is pausing. Deep context mining, self-validation, multi-file splitting. Captures everything the next session needs. user_invocable: true triggers:

  • do a handoff
  • create a handoff
  • run handoff
  • save session context
  • session handoff
  • save session progress
  • running out of context argument-hint: [optional reason, e.g. "context low", "end of day"]

Session Handoff

Guards:

  • Not plan mode. This skill writes files. If in Claude Code plan mode, exit first.
  • Not shadowing. NEVER generate handoff-like documents freeform. Freeform summaries look right but lack chain tracking, self-validation, and evidence mining. Only this skill produces handoffs.
  • Not when discussing. Only run when the user explicitly asks to CREATE a handoff right now. If ambiguous ("what does handoff do", "edit the handoff file"), ask first.

Typical use: ~75% context. You have a lot of conversation to mine — extract maximum value before closing. On 1M context that's ~750K tokens of history.

The user should not need to provide anything — /handoff alone is sufficient.

Arguments: $ARGUMENTS

Compact mode

If $ARGUMENTS contains the word compact-mode, the compact-handoff mod started this run. It replaces the conversation with this handoff when your turn ends, so the turn must finish with nothing pending:

  • Run Steps 1-6 exactly as normal. Anything else in $ARGUMENTS is the framing hint.
  • Step 7: one line only (file path, line count, chain seq). The compaction replaces this turn seconds later, so a full report is wasted output.
  • Ask nothing in this turn. Where a step says to ask (e.g. Tier B "Any doubt"), take its stated default and note the choice in the handoff.
  • Step 8: don't ask. Follow the Yes flow in references/close-session.md (append ## Session Closed, commit, print the paste prompt), skipping its step 4.
  • Print the paste prompt block exactly as the template has it: the PASTE THIS INTO YOUR NEXT SESSION: header, the dashed rules, the (seq {N}, {chain_tag}) line and the onboarding steps. The mod sends that block as the next prompt word for word. Never shorten it to one line, even when you reused or restored an existing handoff instead of writing a new one.
  • End your turn with this exact last line, path relative to the repo root: COMPACT-HANDOFF-READY: {handoff path}
  • If no handoff file could be written, end with COMPACT-HANDOFF-FAILED: {reason} instead. The mod then leaves the context untouched.

Agent Strategy

Parallelize independent research. Launch in one message.

WhatModeWhy
Step 1A (git/beads/ls)Parallel Bash, never agentsCheap commands; agent bootup wastes 15K+ each
Step 1B context agents (OV, stale-refs, bible)Parallel Bash inline; agents only if parent handoff >500 linesIndependent research
Step 1C (conversation mining)Main agent onlyOnly you have the history
Steps 5+6 (beads/memory writes)Parallel BashIndependent writes

Step 1: Deep Context Gathering

1A: External State (parallel Bash — never agents)

Run in one message as inline Bash calls:

CommandsReturns
git log --oneline -20, git diff --stat, git status -s | head -30, git branch --show-currentBranch, recent commits, uncommitted changes
bd list --status=in_progress, bd list --status=open --priority=0,1, bd stats (skip if bd unavailable)Active/open beads
ls plans/handoffs/, ls .claude/handoffs/, ls plans/*.mdExisting handoff files

1B: Chain Detection

Resolve the chain tag (use first that applies):

  1. Epic exists → use epic name/ID
  2. 1-4 beads → use all bead IDs (e.g., myproject-xxxx, myproject-yyyy)
  3. 5+ beads → pick 2-3 most relevant to the primary work stream
  4. No beads/epic → generate fallback: python -c "import secrets; print(secrets.token_hex(4))" → standalone-{hex}

Find prior handoff in this chain (two tiers, stop at first match):

  • Tier A — Paste Prompt (deterministic). Did the user start this session by pasting something like Read HANDOFF_foo_date.md (seq 2, chain-x) and continue...? If yes, that file is the parent. Read its header. Continuation — seq = parent's + 1.

  • Tier B — Bead/Epic Scan (heuristic, skips auto-handoffs).

    grep -l "Chain:.*{chain_tag}" plans/handoffs/HANDOFF_*.md 2>/dev/null \
      | xargs grep -L "^\*\*Auto:\*\* true" 2>/dev/null
    

    A shared bead is a CANDIDATE, not proof of continuation. Before claiming the match as parent:

    1. Read the candidate's ## Where We're Going section.
    2. Is current session work a direct follow-on of those steps? (Same feature/fix, continuing the named next-actions?)
    3. Clear continuation → inherit chain, increment seq, set parent.
    4. Unclear or unrelated → treat this as seq 1 (new chain). Add a ## Related Handoffs section listing the sibling file as reference only, NOT parent. A bead can host many independent work streams (brainstorm → impl → testing) — don't conflate them.
    5. Any doubt → ask the user: "Found prior handoff {file} on same bead. Is this session a continuation? (default: new chain)"

Neither tier matches: seq 1, parent: none.

1B-3/4: Context Agents (parallel, inline Bash unless parent is huge)

Once chain tag resolved, launch in parallel:

TaskReturns
OV Recall (if available): /memory-recall with 2-3 keyword searchesPrior decisions, failed approaches
Parent Context (if parent exists): READ FULL PARENT — extract Goal, Where We Are, Key Decisions, What We Tried, Where We're Going, Open Questions, code identifiersParent summary for "Since Last Handoff" + identifier list
Reference Docs: ls plans/*BIBLE* plans/*bible* *BIBLE* CLAUDE.md .claude/CLAUDE.md and read if foundProject context
Stale Refs (if parent)
Read the complete source ↗