End every AI session with a /handoff

Sep 3, 2026 · by Terry Peterson · claudeworkflowhabitscli

Who this is for: People who use Claude Code in the terminal (CLI). Browser-only AI users: the idea carries over, but use your AI to re-write the steps.

AI sessions end. Context windows fill up, laptops close, the next morning arrives. The AI session that helped you yesterday remembers none of it. For a one-off question that’s fine. For a project that runs for months, it’s the whole problem.

The fix I landed on was to have AI write it’s future self a set of notes, and the first thing the next session does is read it.

I use to manually request for Claude to write itself a handoff each time, but the results weren’t always consistent. Since I run multiple projects, I needed to standardize this, so I had Claude Code create a /handoff skill. This way all my project know to store a session-latest.md in the repo, and it always answers four questions:

What is the state right now? Is anything half-done, or unpushed, or running in the background, and includes instructions to check, not just assume from memory.
What did this session do, summarized in plain English, not commit messages.
What must be verified next time? Code that passed a test today is not the same as verifying an overnight job produces the right results tomorrow. The next session is the one that will see the result, so tell it where to look.
What comes next, in order, plus the decisions that were already made so they do not get brought-up or asked again.

A few things that turned out to matter A TON:

One file, overwritten every time. Git history is the archive. A folder of dated handoffs just becomes a folder nobody reads.
Write it for a reader with less context than the writer. The session that writes it knows everything; the session that reads it knows nothing. Names of files and their repository, not high-level descriptions of them like “check the logs.”
Include “do not relitigate”. AI is eager to re-open settled questions. A short list of decisions and why they were made saves a surprising amount of time (and tokens).
Make the AI write it, not you. It has the full context of what it just did. Your job is to read it and correct anything that’s wrong. Admittedly with a dozen on-going Claude Code projects, I no longer read these. But early on I had to ask Claude to refine the skill a few times based on what I found.

If you only adopt one habit from this blog, this is the one.

Create a `/handoff` skill for Claude Code that I can run at the end of every session.
Put it in `~/.claude/skills/handoff/SKILL.md` so it works in every project I open.

## What the skill does

When I type `/handoff`, write a file named `session-latest.md` in the root of the
current repository, overwriting whatever is there. Do not create dated copies; git
history is the archive.

Before writing, check the real state rather than relying on memory:
- run `git status` and `git log -5 --oneline`
- note any uncommitted or unpushed work
- note any background processes, jobs, or deployments this session started

## What the file must contain, in this order

1. **State right now.** What is half-done, uncommitted, unpushed, or still running.
   For anything in progress, include the exact command to check its status, not an
   assumption about how it went.

2. **What this session did.** Plain English, a short list. Not commit messages.

3. **What must be verified next session.** Anything that passed today but whose real
   result only appears later (an overnight job, a scheduled task, a deploy). Say
   exactly where to look: file paths, URLs, commands, log locations.

4. **What comes next, in order.** The next steps as a numbered list, most important
   first.

5. **Do not relitigate.** Decisions already made this session or earlier, each with a
   one-line reason. The next session should not reopen these or ask about them again.

## How to write it

- Write for a reader with less context than you. The next session knows nothing.
  Use file names with their repository paths, function names, and commands. Never
  write "check the logs"; write which logs and how.
- Keep it short enough to read in two minutes. Cut anything the next session can
  learn from the code or git history itself.
- Do not include secrets, keys, or credentials, even if they appeared in this session.
- After writing the file, commit it with the message `handoff: <one-line summary>`
  if the repo is clean apart from this file. If other changes are uncommitted, leave
  the commit to me and say so.

## Also do this

Add a line to my global `~/.claude/CLAUDE.md` (create it if needed) that says: at
the start of every session, if `session-latest.md` exists in the repo root, read it
before doing anything else, and confirm in one sentence what state the project is in.

## Finish by

Running `/handoff` once on this repository so I can see the output, then show me the
skill file and the CLAUDE.md line you added.