session-handoff

session-handoff

One-shot "hand off this session" command for capturing a resumable handoff across multiple parallel Claude Code sessions. Reads the current CLAUDE_CODE_SESSION_ID, drafts a substantive summary from the conversation, persists it to disk and to engram, and emits the resume command.

Triggers: /session-handoff, session handoff, park session, me voy a dormir, guardar sesion, guardá la sesión, handoff session, nos vemos mañana, cerremos por hoy, hasta mañana, cierre de día

Purpose

Working very late across 3+ Claude Code sessions in parallel makes it impossible to remember tomorrow which session was attacking which problem. This skill drops a tagged breadcrumb per session: a real summary you can read in 30 seconds and resume the EXACT session by ID with one command.

The handoff lives in two places:

docs/handoffs/session-<id>-<slug>.md — readable by you, by your IDE, and by any future Claude session opened in that project. Versioned in git so the plan survives, is visible on the remote, and the SessionStart hook can index it on the next start (engram-session-start.js reads this directory).
Engram with topic_key: handoff/<slug> and the session_id embedded — searchable from any future session in any project via mem_search handoff.

Process

The skill runs end-to-end with NO user interaction. No drafts to confirm, no slug to pass, no questions. The user invoked this because they want to stop thinking — respect that.

Step 1 — Read the session ID

Read the environment variable CLAUDE_CODE_SESSION_ID. Use the full UUID (do NOT truncate). If the variable is empty, abort with a one-line message: session-handoff: CLAUDE_CODE_SESSION_ID not available in this environment — cannot hand off.

echo "$CLAUDE_CODE_SESSION_ID"

Step 2 — Derive a slug from the conversation

Analyze the conversation history and produce a 3-5 word kebab-case slug that captures the PROBLEM being worked on (not a generic verb). Examples of good slugs:

pro-plus-duplicate-customer
n-plus-one-user-list
auth-middleware-token-leak
session-handoff-skill-creation

Bad slugs (do NOT use):

session-work, debug-stuff, today, wip, task — useless tomorrow.

The slug MUST be ≤ 60 chars, lowercase, alphanumerics + hyphens only.

Step 3 — Draft the summary from the conversation

Read the conversation context and fill these sections substantively. These are NOT placeholders — they are the entire point of the document.

Section	What goes here	Length
`## Qué estábamos haciendo`	The OBJECTIVE of the session — what problem we were attacking, why it mattered, the user's original ask.	2-4 lines
`## Dónde quedamos`	Concrete current state — what was done, what decisions were made, what is half-finished, what is blocked.	2-4 lines
`## Próximo paso`	1-3 bulleted, actionable items — the FIRST thing to do tomorrow when reopening. Each bullet must be doable, not abstract.	1-3 bullets
`## Archivos tocados / relevantes`	Files modified or central to the discussion, with a one-line reason each.	bullet list
`## Contexto técnico clave`	Only if there is a non-obvious gotcha, a key decision, a command to remember, or an external link. Omit the entire section if there is nothing substantive.	optional

Write in the same language the user has been using in the session (Colombian-style Spanish or English). Default to the dominant language of the session.

Step 4 — Pick a title

The first line of the document is # <Title>. The title is one human-readable sentence that names the problem — NOT the slug. Examples:

# Pro Plus: duplicate customer on signup flow
# N+1 query in /api/users list endpoint
# Creating session-handoff skill for resumable session capture

Step 5 — Write `docs/handoffs/session-<id>-<slug>.md`

Path is relative to the CURRENT working directory (the project root). Create docs/handoffs/ if missing. Use this exact structure:

# <Title>

**Session ID**: <full-uuid>
**Resume con**: `claude --resume <full-uuid>`
**Fecha**: <YYYY-MM-DD HH:MM>
**Proyecto**: <basename of CWD>

## Qué estábamos haciendo
<2-4 lines>

## Dónde quedamos
<2-4 lines>

## Próximo paso
- <actionable item 1>
- <actionable item 2>

## Archivos tocados / relevantes
- `path/to/file.ts` — <why it matters>

## Contexto técnico clave
<omit this section entirely if nothing substantive>

Use the current local date/time for the Fecha field. Use the basename of CWD for Proyecto.

Step 6 — Save to engram

Call mem_save with:

title: same as the document title
type: discovery
scope: personal
project: basename of CWD — mandatory. A mem_save without project lands with project=NULL and is invisible to every project-scoped search; that is an INVALID save. After saving, verify with mem_search(query: "<slug>", project: "<basename of CWD>") — the verification search MUST pass project, or it shares the defect and cannot detect an omitted field. If the row does not appear, re-save with the canonical value.
topic_key: handoff/<slug>
session_id: the full UUID from Step 1
content: a structured block following the global engram format. A handoff is recall-critical, and users search in their own words, not ours — so the FIRST line MUST be a KEYWORDS: line listing the user's likely spellings and variants of the topic (e.g. KEYWORDS: lowpoly low-poly diorama), bridging FTS across hyphenation and alternate forms:

KEYWORDS: <user's likely spellings/variants — hyphenated AND joined forms>
**What**: <one-line summary of what the session was doing>
**Why**: <user's motivation / original ask>
**Where**: <files affected, comma-separated>
**Learned**: <gotchas or key decisions, if any — else omit this field>

**Session ID**: <full-uuid>
**Resume**: `claude --resume <full-uuid>`
**Handoff doc**: docs/handoffs/session-<id>-<slug>.md
**Next step**: <first item from the Próximo paso list>

Step 7 — Persist the session summary to engram

A session-handoff is a real close, not just a breadcrumb: afterward the user usually opens a NEW session (different project, or the old session expired), so engram MUST carry a session summary, not only the handoff blob. Call mem_session_summary using the mandatory template defined in the global CLAUDE.md ("mem_session_summary template" section) — use ALL its sections verbatim, including the Session ID line that embeds the recovery anchor. Do NOT re-enumerate the sections here; the global file is the single source of truth and this skill inherits its changes. Pass project = basename of CWD.

This does NOT end or kill the session — a summary records state; the user can still claude --resume <id> tomorrow and keep working. The two are complementary: the handoff (Step 5) is deterministic disk recovery, the summary (this step) is associative engram recall. A day-over close persists both.

After saving, verify with mem_search on the summary, scoped to project, per the global post-save validation rule. If it does not land, retry once, then tell the user the summary failed — do not claim it persisted.

Step 8 — Print the resume command

After all writes succeed, print exactly ONE line to the user — no extra commentary, no follow-up question:

📌 Handed off. Resume with: claude --resume <full-uuid>

(The pushpin emoji is the ONLY emoji allowed in this skill's output. It is a deliberate signal that the session is handed off.)

If any step in 5-7 failed, print the error AND still print the resume line if the session ID is known — the user must be able to reopen tomorrow even if a write didn't complete.

Rules

Zero interaction. Never ask the user anything. Never show a draft for confirmation. The user invoked this because they want to stop thinking.
Read CLAUDE_CODE_SESSION_ID directly. Do not ask the user for it. Do not truncate it. Use the full UUID everywhere it appears.
Substantive sections, not placeholders. ## Qué estábamos haciendo, ## Dónde quedamos, and ## Próximo paso must be filled from the actual conversation. If you cannot fill them, you did not read the conversation — re-read before writing.
Slug must name the PROBLEM, not the activity. debug-stuff and wip are banned.
docs/handoffs/ is versioned in git, NOT gitignored. The handoff is the project's deterministic recovery source — the SessionStart hook indexes this directory on the next start. Hiding it from git would break that path. Do NOT add docs/handoffs/ to .gitignore; if a prior version of this skill added it, leave the entry removal to an explicit user request (do not touch .gitignore here).
Engram save mirrors the document. Same title, same problem, with the session_id embedded so future mem_search handoff returns this entry. project is mandatory and the save is verified with project set (Step 6); the content's first line is a KEYWORDS: line in the user's own spellings.
Match the session's language. If the conversation was in Spanish, write the handoff in Spanish. If English, English. Section headers stay in Spanish as defined above — they are the skill's contract.
Output is ONE line at the end. The resume command. Nothing else. The user wants to stop and move on.
No commit, no push, no git operations. The handoff is left as an unstaged working-tree change; the user commits it when they choose. It is swept into git deterministically at the NEXT SessionStart by the engram-session-start handoff-sweep emit. On a work branch the emit directs the sweep commit right away. On the default branch (master/main) the emit DEFERS: no commit lands on master and NO dedicated sweep branch is created — the pending docs are folded into the FIRST work branch the session creates, and the notice RE-SURFACES every SessionStart until a work branch absorbs them. Per the global rule "never commit without explicit user request for THAT action".
Persist BOTH a handoff and a session summary. A session-handoff is a real close: the handoff (Step 5) is deterministic disk recovery, the mem_session_summary (Step 7) is associative engram recall. Save both — the next day the user often opens a fresh session, so engram must carry the summary, not only the handoff. The summary records state, it does NOT end the session: claude --resume <id> still works tomorrow.