A Claude Code skill that packages a working session into a structured, resumable handoff file — so the next agent (or the next you) picks up with the plan, locked decisions, learnings, and action items intact instead of re-deriving them from a bloated context window.
Long Claude Code sessions accumulate hundreds of thousands of tokens. Past a point, every turn is expensive and compaction starts eating the reasoning that made the session effective. The cheapest fix is deliberate: distill the session's transferable state into a small file (~2–10K tokens), start fresh, and resume from the file. This skill makes that a one-command habit in both directions:
/session-handoff— write the handoff file, report the context savings/session-handoff resume <path|TICKET>— read a handoff, verify the world hasn't drifted, and continue the work
git clone [email protected]:crd/session-handoff.git ~/.claude/skills/session-handoffRestart Claude Code (or start a new session) and the skill is available as
/session-handoff.
| Command | Effect |
|---|---|
/session-handoff |
Create a handoff file for the current session |
/session-handoff portable |
Also print a copy-paste prompt for readers without filesystem access (web Claude, other assistants, humans) |
/session-handoff resume |
List ACTIVE handoffs and pick one |
/session-handoff resume <absolute-path> |
Resume a specific handoff |
/session-handoff resume PROJ-123 |
Resume the ACTIVE handoff for a ticket |
Natural-language phrasings work too: "save this and hand off", "pick up where I left off".
| Setting | Default | Override |
|---|---|---|
| Handoff directory | ~/Documents/handoffs |
SESSION_HANDOFF_DIR env var |
| Ticket system | any short key (PROJ-123, GitHub gh-123) |
— |
| Forge CLI for MR/PR detection | glab or gh, best-effort |
— |
Handoffs are organized as <dir>/<TICKET>/YYYY-MM-DD_HHMM_<slug>.md, with
ticketless work under _untracked/.
Each handoff is a single markdown file with YAML frontmatter
(status: ACTIVE | COMPLETED | SUPERSEDED) and required sections:
- Live Refs — one-click URLs: ticket, MR/PR, session transcript
- Goal / Plan — inlined in full, never referenced by path
- Decisions Locked — choices not open for re-derivation, including mid-session user preferences
- Learnings — tried-and-rejected approaches, gotchas, load-bearing docs
- Artifacts — changed files as absolute
path:linereferences - Action Items — concrete next steps
- Execution Notes — running processes, auth state, WIP
- How to Resume — fresh-context vs
claude --resumeguidance based on how full the originating session was, plus a portable prompt block
The resuming agent verifies git/artifact/MR state against the file, classifies the situation (clean continuation, diverged codebase, incomplete work, stale handoff), presents a plan, and marks the handoff COMPLETED when done.
MIT — see LICENSE.
