handoff
Skill1 starsChanged 35 days agoMITView on GitHub
Judge the context move (continue / compact+handoff / fresh+handoff) and act on it; compact and fresh write the handoff to a file. Fire when the user asks for /handoff or whether to hand off ("should we /handoff?"): this skill is the evaluation, never answer that from memory. Pass their words as args, not a route. Also "hand this off", "should we compact / go fresh?", "context is getting high". NOT /wrap-up or /done-check.
191 other projects use a version of this.
Adopted by
Most recently taken up by
- tanishq286/tq-forgetheir own version, first seen Nov 15, 2026
- niki914/zafirotheir own version, first seen Nov 15, 2026
- davidondrej/skillstheir own version, first seen Nov 15, 2026
- quickchatai/quickreviewtheir own version, first seen Nov 15, 2026
- HiteSit/real-scientist-skillstheir own version, first seen Nov 15, 2026
- alexj11324/Mikkatheir own version, first seen Nov 15, 2026
Used with
Projects with it also use decision-mapping, setup-ts-deep-modules and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
FabienDehopreSkilldecision-mapping
Turn a loose idea into a sequenced map of investigation tickets, then drive them to resolution one at a time.
Also in 8 projects that use this
liufeng1976Skillsetup-ts-deep-modules
Wire dependency-cruiser into a TypeScript repo so each package is a deep module — implementation hidden in subfolders, reachable only through its entry-point files. User-invoked.
Also in 42 projects that use this
AWSSkillto-questionnaire
Turn a decision you can't fully answer into a questionnaire for someone else to fill in.
Also in 93 projects that use this
GoogleSkillask-matt
Ask which skill or flow fits your situation. A router over the skills in this repo.
Also in 87 projects that use this
RoentekSkillloop-me
Grill me about specs for the workflows I want to build, within this workspace.
Also in 51 projects that use this
LesaniSkillwriting-beats
Shape an article as a journey of beats, choose-your-own-adventure style. The user picks a starting beat from the raw material, you write only that beat, then offer options for where to pivot next, beat by beat, until the article reaches a natural end. Use when the user has raw material and wants to assemble it as a narrative rather than an argument.
Also in 54 projects that use this
Other versions191 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 191
- mattpocock/skills★ 325ksame name
- QuivrHQ/quivr★ 40ksame name
- The-Vibe-Company/quivr★ 40ksame name
- GreyDGL/PentestGPT★ 16ksame name
- ykdojo/claude-code-tips★ 10ksame name
- ArcReel/ArcReel★ 6.6ksame name
- vinvcn/mattpocock-skills-zh-CN★ 5.8ksame name
- withcoral/coral★ 4.9ksame name
- epicenter-md/epicenter★ 4.8ksame name
- EpicenterHQ/epicenter★ 4.8ksame name
181 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository56 other files it gives its agents.
- autopilotSkill
- before-afterSkill
- bigpictureSkill
- blast-radiusSkill
- brainstormSkill
- compoundSkill
- confidence-checkSkill
- contextualizeSkill
- create-ship-skillSkill
- create-skillSkill
- curateSkill
- debugSkill
- deep-researchSkill
- devtoolsSkill
- distillSkill
- done-checkSkill
- doneSkill
- double-checkSkill
- envsetSkill
- explainSkill
- fortifySkill
- goSkill
- harness-auditSkill
- interviewSkill
- matrixSkill
- mockupSkill
- mutateSkill
- notesSkill
- postmortemSkill
- presentSkill
- qaSkill
- readableSkill
- recommendSkill
- reportSkill
- retireSkill
- review-planSkill
- scoutSkill
- sec-reviewSkill
- setup-ticketingSkill
- setup-worktreesSkill
- spec-checkSkill
- specSkill
- stepsSkill
- successionSkill
- super-reviewSkill
- tangentSkill
- tddSkill
- tend-memorySkill
- testSkill
- ticketSkill
- tldrSkill
- triageSkill
- waitSkill
- workSkill
- worth-itSkill
- wrap-upSkill
The file
We split this skill into the rules it gives an agent
2 rules. 0 are common, 2 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 172 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 21
No stated intent and no obvious next move → ask what's next rather than invent one.
- Distinctive: line 102
Don't echo the handoff body into chat.
“Common” is measured: kept by at least 6 in 10 of the 172 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Two jobs: judge the context move and act on it, then, unless the verdict is continue, write the handoff: the delta the next session can't reconstruct from the repo, CLAUDE.md and memory.
Step 1 — Absorb the user's intent
The user usually types /handoff in the same prompt where they say what comes next, or the last response already named the next move. That intent is the spine of the handoff; the next session exists to carry it out.
- Carry it in their terms. Strip dictation filler, but don't reinterpret, merge, or reorder what they asked for.
- If any of it is unclear (which of two things goes first, a "the other thing" this thread can't resolve, a step that conflicts with what the thread established), ask before judging or writing: one AskUserQuestion round, your recommendation first. A handoff built on a misread intent is worse than none. This is the only pause the skill allows.
- No stated intent and no obvious next move → ask what's next rather than invent one.
Step 2 — Judge the move
Skip if the user named the route themselves ("compact this", /handoff fresh). A route word in args the calling model wrote is its guess from before it read this step: judge from scratch.
Measure, don't estimate.
- Context used: the percentage on your statusline, or
/context. Thetotal_tokensfigure in system reminders is the run's budget, not context room. - Live work: each background shell, watcher or subagent this session started that hasn't reported back: what it waits on, its task id, its output file.
Place the next slice against this thread. Go by what it touches, not by whether it has its own ticket or PR number; most slices do.
- Continuation: the next rung of this thread's own work. Same branch, PR or bug; the rollout or close-out of what was built here; the build of a spec settled here.
- Sibling: same feature or epic on its own branch, sharing code, data or domain rules with this thread.
- Unrelated: nothing this thread settled applies.
Route on that:
- Continue: a continuation whose rest is a few turns, or that finishes with the window under about half. If the rest branches (green → close out, red → debug), size it by the long branch. Say so plainly, then start the work in the same turn. No file.
- Compact + handoff: a continuation too big for that, or a sibling that leans on what this thread settled. Flow: write the handoff → the user runs the
/compactfocus line → they paste the path into the compacted thread. - Fresh + handoff: unrelated work; work that runs alongside this session or needs another repo, machine, model or effort level (a new window, not
/clear); or a thread that held a wrong model for a stretch (retracted findings, a long dead end) that a summary would re-anchor the next session on.
What compact keeps. /compact swaps the transcript for a structured summary: every message the user sent, the errors and fixes, files and code touched, pending work. Recently edited files and loaded skills come back with it; raw logs, QA dumps and tool output don't. A compacted window typically lands at a small fraction of where it started, not far above a fresh start. Nothing on disk is lost: the session file keeps every earlier record above the compaction marker. Finished-work residue is no case for fresh, because compact drops it too. The summary keeps what a handoff's cut test throws away (the user's corrections, ruled-out approaches, why calls went the way they did); the handoff keeps what a summary blurs (paths, SHAs, guardrails, their intent word for word).
Don't route by asking whether the handoff could carry everything. Its author can't see what it would drop, so the answer is always yes. For related work, lean compact: a needless compact costs a summary's worth of tokens, a needless fresh costs whatever the handoff missed.
Live work changes the route only when its result lives in this session. Background shells keep running through /clear and through /compact; their finish notice lands in whichever session holds the terminal by then. Treat a subagent the same way; that part is unverified.
- Re-checkable from outside (a CI pipeline, a PR, an email, a deploy): any route. The handoff says how to re-check.
- Only in this session (a task output file, a subagent's report): compact, or fresh via
/clear. The handoff lists the task id, what it waits on and its output path, and says not to start a duplicate. Not a new window: the notice stays with this session. - Due within minutes and the rest is short: continue, and run this skill again when it lands.
This usually runs at a natural seam with a heavy window, so continue is rare, and compact and fresh should both come up often. A continuation or sibling routed fresh must name the fresh trigger that applied.
Step 3 — Write the handoff (compact / fresh only)
Save to a durable, git-ignored folder in the main checkout, e.g. <main checkout>/docs/local/<ticket-or-slug>/handoff-<ticket-or-slug>.md (add docs/local/ to your global git ignore), overwriting an earlier one. Main checkout = git worktree list | head -1: removing a linked worktree deletes its ignored files. Outside a repo, use the session scratchpad. /tmp doesn't survive a reboot, so avoid it for anything the next session must find.
The file is only the handoff: the user pastes its path, so nothing from this session's chat reaches the next one. Open with a line that addresses the reader:
> **Handoff for the <fresh | post-compaction> session reading this: you are its target, act on it.** Written <YYYY-MM-DD HH:MM>.Write to the target. Compact → a thin pointer: the summary keeps the story, so carry what summaries drop (exact paths, SHAs, branch/worktree state, hard "do NOT" guardrails, the user's intent word for word). Fresh → the fuller memo; the reader starts cold except for CLAUDE.md and memory.
Building blocks, not a template; use ## headers and pick what earns its keep.
- The user's intent: what they asked for next, in their words (Step 1). Present whenever they stated any.
- Where we are: what just landed, current status. Near-universal.
- Branches / working dirs: branches in play, commit/push state, worktree paths. When non-trivial.
- In flight: each still-running task (id, what it waits on, output path) and how to re-check it if its notice never arrives.
- Start here: numbered first steps. When the next move maps to a driver skill, name it in step 1; it tells the next session how to proceed, not just what's next. Most handoffs are a scoped slice ("here's the work, go execute"), which almost always maps to the project's build/ship driver, so treat not naming one as the exception that needs a reason. Resolve the skill from the registry actually available, and match by kind of move; naming the wrong driver is worse than naming none:
- build-and-land a feature/fix → the project's ship-class composite if present (build → local QA → PR); else its build driver (
/work) plus a note that landing is separate. - diagnose an unknown-cause bug →
/debug; confirm a parked branch is deploy-safe → the project's readiness gate; orient / pick what's next, or a blocked decision →/recommend. - anything that doesn't map cleanly → plain numbered steps, no driver.
- build-and-land a feature/fix → the project's ship-class composite if present (build → local QA → PR); else its build driver (
- Scope / ground rules: conventions and hard constraints, including first-move guardrails ("do NOT fix until the root cause is agreed").
- Out of scope: deferred items, bugs handled elsewhere.
- Open questions or Starting hypotheses: unresolved ambiguities; for debug handoffs, ranked theories to validate first.
Rules of thumb:
- Cut test: would the next session act differently without this line? If not, cut it. Anything it can re-derive in one step (the ticket description,
git log, a file) gets a pointer, not a restatement. - Concrete paths, branches, SHAs. Mutable state gets a timestamp and a re-check instruction ("as of 16:39, re-verify"):
git status, test results, and "HEAD is at X" go stale fastest when another session is live in the same repo. - Tag load-bearing claims by provenance: ✅ a tool result this session shows it · 🧠 recalled (memory, an earlier handoff, a peer session) · 🔗 inferred · ❓ assumed. Tag the claim the next session will act on, not just the number under it: a ✅ measurement under a 🔗 conclusion is still 🔗. (Full rules:
/confidence-check.) - Typically 25–80 lines; compact pointers shorter.
Output
In this order, nothing before the verdict:
- The verdict line, naming why the runner-up lost:
→ continue: <reason>, then go straight into the work.→ compact + handoff: <reason> (fresh lost: <why>)→ fresh + handoff: <reason> (compact lost: <why>)
- Basis, one line, so the user can check the read:
ctx <N>% · <continuation | sibling | unrelated>: <the slice> · live: <tasks, or none>. - Intent, as captured: 1–4 bullets, so the user can check the read without opening the file.
- Optional sender notes (ticket updated, a non-obvious shaping choice): 1–2 sentences.
The move and the absolute path, last, each in its own code block:
- Compact: "run this, then paste the path:", then
/compact Keep: <what the next slice needs from the thread>. Drop: <the finished work's raw output>.on its own line (plain words, no@, no path), then the path. - Fresh, replacing this session: "
/clear, then paste:", then the path. - Fresh, alongside this session: "New session, paste:", then the path.
Make the handoff file's path the only
handoff*.mdpath in this reply, so it's unambiguous to copy.- Compact: "run this, then paste the path:", then
Don't echo the handoff body into chat; the file is the handoff.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

