| name | session-handoff |
| description | Transfer full working context to a fresh agent session with zero memory — end of session, before compaction, switching models/agents mid-project, or pausing multi-day work. Use when asked for a handoff, handoff doc, session transfer, "deja esto listo para la próxima sesión", context dump for another agent, or when a long session is about to hit context limits. Not for delegating a bounded task (use codex-handoff) or for task cards (use handoff-task / brain_task tools). |
| owner | platform |
| created | "2026-07-05T00:00:00.000Z" |
| created_by | claude-fable-5 |
| sources | adapted from davidondrej/skills (handoff, MIT) |
Session Handoff
The next session knows nothing. A good handoff gives it ground truth to reason from, not a to-do list to obey — the fresh agent has judgment; feed it state, and it will find the right next action even where your plan was wrong.
The core discipline: state, not instructions
Write "logout is implemented; token revocation is NOT — revoke endpoint returns 501", not "implement token revocation next". Instructions encode your guesses; state lets the successor re-derive them. The only instructions that belong in a handoff are constraints (gates, rules, things that must not be done).
Where it goes
- Durable project work →
knowledge/projects/<project>/HANDOFF-<topic>-YYYY-MM-DD.md (Brain = any successor agent on any node can read it).
- Ephemeral / same-machine continuation → a local file is fine, but if the work matters, Brain.
- Never in chat only — chat dies with the session.
Template (7 sections, all load-bearing)
# Handoff: <topic> — YYYY-MM-DD
## Goal
<what finished looks like, 1-3 sentences — the bar, not the steps>
## Why / background
<the minimum a stranger needs to understand why this work exists>
## Current state ← the heart; be exhaustive here
<what IS true right now: what works, what doesn't, what's half-done.
Verified facts with evidence ("X passes: <command> → <output>"), not recollections.>
## Key decisions (+ why)
<decisions already made and their reasons — so the successor doesn't relitigate
them without new evidence. Include decisions the founder made explicitly: those are gates.>
## Traps & dead ends ← highest value per line
<approaches already tried that failed, and WHY. One line each.
Also file durable ones per failure-archaeology.>
## Relevant files & pointers
<paths, Brain docs, PRs, dashboards — REFERENCE, don't paste content.
Duplicated content goes stale; pointers stay honest.>
## Open work
<what remains, as state ("gate 3 unverified") — ordered by importance, not chronology>
Rules
- Reference, don't duplicate. Point to specs/docs/PRs by path. A handoff that pastes 3 docs is stale the moment any of them changes.
- Secrets: name where credentials live (
$SOURCE_SYSTEM_TOKEN, approved secret store) — never values.
- Claims are verifiable or labeled. Anything you didn't verify this session gets "(unverified)". A confident stale claim poisons the successor's whole run.
- Closing instruction for the successor — end every handoff with: "Read every referenced file before acting. Treat every claim above as context to verify, not fact to trust."
- Written before you're out of context, not after — a handoff drafted at 2% context is a lottery ticket. If a session is long and the work matters, draft the handoff at the natural pause, then keep working.
Guardrails
| ❌ | ✅ |
|---|
| To-do list of instructions | State + constraints; successor derives the actions |
| "Everything mostly works" | Per-item state with evidence |
| Omitting failed attempts (embarrassing / irrelevant) | Traps & dead ends section — it's the most valuable one |
| Pasting doc contents to be "self-contained" | Pointers by path; self-contained means coherent, not complete-copy |
| Handoff only in the chat / final message | File in Brain (or repo) at a predictable path |
Verification
Done when: file exists at the stated path, brain_read returns it (if Brain), every referenced path in it resolves, and a zero-context read of "Current state" alone would let an agent continue without asking the founder anything already answered.
Cross-references
- Bounded task delegation (different job): internal
codex-handoff skill (not included in this public package)
- In-flight spec transfer: the spec's own "Next Agent Prompt" section — spec-driven-execution
- Task cards with handoff prompts: local skill
handoff-task + brain_task_create (MCP)
- Dead ends worth keeping forever: failure-archaeology
Provenance and maintenance
- Brain handoff location convention (
knowledge/projects/<project>/HANDOFF-*.md): pre-existing practice, verified 2026-07-05 (e.g. knowledge/company/digital/HANDOFF-paid-dtc-investigation*). Re-verify: brain_search("HANDOFF").
handoff-task local skill + brain_task_create MCP tool: verified 2026-07-05. Re-verify: skill_search("handoff").
Cambios
| Fecha | Cambio | Por |
|---|
| 2026-07-05 | Created — davidondrej handoff pattern (state-not-instructions, traps section, verify-don't-trust) adapted to Brain paths and the reference deployment gates. | Claude Code (Fable 5) |
