Session Handoff

Session Handoff

When this fires

A long session accumulates decisions, dead ends, and verified facts that live only in the conversation. When that conversation gets compacted or a new session has to pick up the work, all of that is at risk of being silently lost — the next session either re-derives it (slow) or contradicts it (worse). This skill's job is to decide, before the flush happens, exactly what is worth keeping and write it down in a form a cold session can use without re-reading the whole history.

Protocol

1. Detect the trigger. Confirm this is actually a long-session boundary:

context-limit warning, explicit compaction, or the user asking to pause and resume later. Do not run this for a task that is about to finish.

1. Extract durable state only, pulling from the actual conversation —

never from inference or assumption:

• Architecture / design decisions that were made, and why
• Edge cases or bugs already found (so they aren't re-discovered)
• The file map: which files matter and what each one is for
• Open threads: what's unfinished, blocked, or explicitly deferred
• What's verified (ran, tested, observed) vs. assumed (stated but

not checked)

1. Write HANDOFF.md (or, if no file should be written, print the same

content as a block) using the fixed template in Output below.

1. List what can be safely dropped from context now that it's captured

in the handoff — this is what makes the handoff worth writing.

Hard rules

• Never invent a decision, rationale, or fact that wasn't actually

established in the session. If something is unclear, list it under Open Threads instead of guessing.

• Every claim goes in either Verified or Assumed — never blur the two.
• Keep the handoff under ~40 lines. If it's longer, cut detail, not

sections — a bloated handoff defeats the purpose.

• Do not re-explain code that's readable from the files themselves; capture

only what isn't recoverable by reading the repo (decisions, rejected approaches, in-progress state).

Output

A HANDOFF.md in this exact structure:

# Handoff: 

## Decisions made
-  — 

## Edge cases already caught
-  — 

## File map
-  — 

## Verified vs assumed
- Verified: 
- Assumed: 

## Open threads
- 

## Safe to drop
- 

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pinexai
• Source: pinexai/claude-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.