The Session Handoff Skill: End Every Claude Code Session Without Losing Context

The problem with long Claude Code sessions

Every Claude Code session has a context limit. When you hit it — or when you clear the session and start fresh — everything in the current conversation is gone. What you were building, what decisions were made, what files were changed, what's still running in the background.

If the next session picks up without that context, it starts blind. You re-explain the goal. You re-check which files were touched. You find out mid-task that a background process was already running and now there's a conflict.

The session handoff skill solves this by producing a structured summary before you clear — a document written for the next agent, not a status report written for a stakeholder.

How the skill works

The skill triggers when you say any of these phrases: "session handoff", "wrap up session", "hand off", "handoff summary", "let's wrap up", or "summarize before I clear."

Claude reviews the full conversation — not just the last few turns — and produces a structured summary in chat. It pulls state from plan files referenced in the session, TodoWrite task state, any background processes started with

run_in_background

The output goes to chat only. The skill never writes a file. The point is a clean handoff artifact that the next agent reads before doing anything else.

The handoff template

Every handoff uses this structure, every time. Consistent structure is the whole point — if sections appear in different orders or get omitted, the next agent has to search for the information rather than reading it in a predictable location.

textCopy
# Session Handoff — <one-line title of what this session was about>

## Where it started
<2-3 sentences: what the user asked for, key framing or constraints that emerged>

## Decisions locked + what shipped
- <decision or change> — <why, and where it lives (absolute path if a file)>
- ...

## Key files for next session
- `<absolute path>` — <why the next agent should read this first>
- Plan file: `<path>` (if a plan drove the session)
- Memory files touched: `<paths>` (if any)

## Running state
- Background processes: <shell IDs + what they are + how to kill> — or "none"
- Dev servers / ports: <url + port> — or "none"
- Open worktrees / branches: <paths> — or "none"

## Verification — how to confirm things still work
- `<command>` — <expected outcome>
- ...

## Deferred + open questions
- Deferred: <item> — <why pushed to later>
- Open: <question needing the user's input> — <context>

## Pick up here
<1-2 sentences: the single most likely next action for a fresh agent>

What each section is for

• Where it started — frames the session goal and constraints so the next agent understands why decisions were made, not just what they were. Without this, a decision that looks arbitrary in isolation makes sense in context.
• Decisions locked + what shipped — the authoritative list of what changed and where it lives. Absolute paths always — a relative path is useless if the next agent has a different working directory.
• Key files for next session — tells the next agent what to read first. If a plan file drove the session, it goes first in this list.
• Running state — background process shell IDs, dev servers, and open worktrees. If you started a
  promptCopy

  run_in_background

  process, the next agent cannot find it without the shell ID. Write "none" rather than omitting the section.
• Verification — specific commands the next agent can run to confirm nothing broke. Not "check that it works" — actual commands with expected outputs.
• Deferred + open questions — separates items explicitly pushed to later from items that still need the user's input. Keeps the next agent from trying to resolve deferred scope.
• Pick up here — one or two sentences. The single most likely next action. The next agent reads this first after the title.

Installing the skill in Claude Code

1. Download the skill file to your machine
2. Inside Claude Code, open the Customize menu and go to Skills
3. Click the + button, then Create a Skill, then Upload
4. Upload the skill file
5. The skill is now active in all Claude Code sessions — any trigger phrase fires it

What the skill doesn't do

The handoff is a synthesis of what happened in the current session. It doesn't run

git log

It also doesn't write to memory, update plan files, or save anything to disk. Chat output only — that's by design. If the handoff were written to a file, you'd have to find and read it before every session. In chat, the next agent gets it as the first thing in context.

Frequently asked questions

When should I run the handoff versus just using

/compact

/compact

/compact

What if there are no background processes or dev servers running? Write "none" in the Running state section. Don't omit the section. The structure is the whole point — if sections appear inconsistently, the next agent has to check whether the section was omitted (nothing running) or was forgotten (something might be running). "None" is a definitive statement. A missing section is ambiguous.

Can I use the handoff template manually without the skill? Yes. Copy the template from this post and paste it as a message to Claude at the end of any session: "Using this template, produce a session handoff for the work we just did." The skill just automates the trigger so you don't have to find and paste the template every time. The output quality is the same either way — the structure is what matters, not the trigger mechanism.