handoff
A session needs to end or continue elsewhere — "write a handoff", "I'm running low on context", "continue where we left off". Writes and resumes a handoff that survives compaction.
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- handoff
- description
- A session needs to end or continue elsewhere — "write a handoff", "I'm running low on context", "continue where we left off". Writes and resumes a handoff that survives compaction.
- allowed-tools
- Read, Write, Edit, Grep, Glob, Bash
- user-invocable
- true
02 资源文件 10
- 参考文档references/backlog.md4.9 KB
- 参考文档references/flow.md3.2 KB
- 参考文档references/hooks.md4.3 KB
- 参考文档references/rationale.md2.9 KB
- 参考文档references/template.md2.6 KB
- 脚本scripts/handoff7.4 KB
- 脚本scripts/handoff_cli.py27.7 KB
- 脚本scripts/handoff_session_start.sh4.9 KB
- 脚本scripts/test_handoff_wrapper.py13.9 KB
- 脚本scripts/test_handoff.py33.7 KB
03 SKILL.md 正文
Handoff
A handoff is a controlled /compact: the model that did the work distills a state packet
the next session can safely act on, written for a competent stranger who has the repo and
nothing else. Write it while there's context left to think with, not at 3%.
Files
Scoped per git branch at docs/handoffs/<branch>/ (/ → -; nothing on detached HEAD).
If the repo already has a convention (a HANDOFF.md, a path named in CLAUDE.md), use it.
CURRENT.md— re-entry prompt. Short; exactly one next action. Consumed, then replaced.NARRATIVE.md— what was done and decided, and why. Appended across sessions.BACKLOG.md— work that isn't next. Only touch via the CLI.
Small single-session work can skip the narrative. Why the split:
references/rationale.md. Skeletons: references/template.md.
CLI
If handoff isn't on PATH, use
"${CLAUDE_PLUGIN_ROOT:-${SKILL_TREE_DIR:-$HOME/projects/skill-tree}}/skills/handoff/scripts/handoff".
handoff add --title "..." --body "..."— capture for later (nextfor the top)handoff backlog/current/narrative— read a filehandoff pop— move the top backlog item intoCURRENT.md. Ask the user first.handoff status [--set <keyword>]— status of every project, or set this one'shandoff close— delete this branch's handoff dir; distill keepers toCLAUDE.md/memory first
Flags and repo selection: references/backlog.md.
Reference, don't absorb
Logs, diffs, test output, specs stay where they are — reference by path, command, or ID. Never
write what the repo already answers (file inventories, diff recaps). No PLAN.md: decisions go
in the narrative, the next step in CURRENT.md.
CURRENT.md
- Goal — one or two sentences, including why.
- Anchor — timestamp, branch,
git rev-parse --short HEAD, dirty/clean, handoff counter (#3 of this thread). Run the commands; never from memory. - Read order — which files, in what sequence, which to grep rather than read.
- In flight — the half-finished edit by
file:line, and what it needs. - Next action — one concrete step startable without a decision.
- Acceptance check — the command that proves it worked.
- Open questions — marked blocked, so the next session asks.
Near the top: **Status:** <keyword>, read by the session-start hook and handoff status:
in-progress— mid-flight (popsets this)awaiting-review— done and green, user's turn. Committing past the anchor auto-promotes it to between-tasks.between-tasks— settled. With an empty backlog, suggesthandoff close.
NARRATIVE.md
Ordered by how unrecoverable it is otherwise:
- Tried and failed — what, what happened, why abandoned. The most valuable, most dropped.
- Decisions and constraints with reasons, incl. the user's rejections ("no new dep").
- Done, with evidence —
<claim>—<command>→ result, at<sha>. Useverify. - Lessons and surprises.
Resuming
- Read
CURRENT.mdcompletely; follow its read order. - Check the anchor against reality. HEAD moved → every claim is suspect.
- Re-run the done-evidence. If one fails, correct the narrative first. If it can't run here (service down, env missing), say so and keep the claim — only a real failure invalidates it.
- Skim
handoff backlogtitles, so deferred work is known but not started. - State back goal, state, and next action in a few lines; let the user correct you.
Write-back — per task, same turn, not at session end
- Narrative: append done-claim + evidence, plus any decision, dead end, or surprise.
CURRENT.md: rewrite next action + acceptance check, clear resolved in-flight, re-anchor if committed. Edit in place — replace, never append a second prompt.handoff status --setas state changes.- Anything surfaced that isn't next →
handoff add, never parked inCURRENT.md.
Hook automation: references/hooks.md. Lifecycle diagrams: references/flow.md. Failure
modes: references/rationale.md.
04 同仓库更多 Skills
wait-what
Stop. Your plan/idea did not land. Re-pitch it.
verify
Verify before answering whether something works, still passes, is gone, is used, or is correct — and whenever the user says "can you confirm", "are you sure", "did that actually work", or reports something is "still" broken. Produces the answer plus the evidence that would have falsified it. A failed GitHub Actions run is skill-tree:debug-ci instead.
ui-designer
Design or restyle a web UI — landing pages, dashboards, docs sites, app chrome — or when the user asks why a site "looks generic", "looks like a template", or wants it to feel intentional. A running list of design lessons learned, applied as rules rather than suggestions.
two-axis-review
Two-axis review of changes since a fixed point (commit, tag, HEAD~N, or default HEAD~1): Standards (does the code follow this repo's conventions?) and Spec (does the code do what it should?). Axes run as parallel sub-agents so neither masks the other. Use when the user says "review against the spec", "does this follow our conventions", "standards and spec review", or "two-axis review". Not a correctness bug hunt — that's the built-in `/code-review`.
tui-screenshots
Use for generating or refreshing TUI screenshots for docs — "regenerate the screenshots", "the README screenshots are stale". Drives a Textual/TUI app headlessly and exports SVG. Not for reading a user's screenshot — that is `screenshot`.
to-tickets
Break a spec, plan, or conversation into tracer-bullet vertical-slice tickets with blocking edges — "turn this into tickets", "break this down", "what's the work?". Pairs with skill-tree:to-spec upstream and skill-tree:handoff downstream.