Handoff

The pattern in one phrase: durable context — save your work so a fresh start loses nothing.

1. What it does

When you're about to end a work session, it writes one self-contained file that holds everything the *next* session needs to pick up exactly where you left off — and reads nicely for a human too.

2. The problem it solves

AI agents forget. When a chat gets too long or you start a new one, the agent loses all the context — what you were building, what's done, what's half-broken, what the next step was. So you waste the first ten minutes of every new session re-explaining yourself. It's like coming back from vacation to a coworker who covered your desk but left zero notes — you have to reconstruct everything from scratch.

A handoff kills that. End the session, and the agent drops a complete "here's where we are" file. Next session, you point at it and go.

3. The core pattern (the part you steal)

Durable context: capture state in a structured form, then make the output self-sufficient.

Two ideas are doing the work here, and you can reuse both anywhere:

Separate the content from the shell. The handoff doesn't hand-write a pretty document every time. It gathers the *facts* (what's done, what's next, what broke) into a plain structured list, then pours those facts into a fixed template. Same idea as a mail-merge: you write the letter once, and the names slot in. This is why it's fast and never drifts in quality.
Make the artifact carry its own restart instructions. The file doesn't just *describe* the work — it ends with a copy-paste prompt that tells the next agent exactly what to do first. The handoff is self-sufficient: hand it to a total stranger (or a blank AI) and they can continue. Like a recipe card that assumes you know nothing — it works on its own.

That combo — *structured state + self-sufficient output* — is the transferable lesson. It applies to shift-change notes, project wikis, onboarding docs, anything where someone else has to pick up cold.

4. How the skill is actually built

Look at the real file: ~/.claude/skills/handoff/SKILL.md. Its shape:

Frontmatter (the top block): name: handoff and a description that ends with *"Use when ending a session, context is depleted, or switching tasks."* Those trigger words are the whole game — they're how the agent knows, on its own, that *now* is a handoff moment.
The body: five plain steps. (1) Gather the context into a list. (2) Check git, ask before committing. (3) Pour the content into the template and generate the file. (4) Leave a one-line pointer so it's findable later. (5) Show the result and offer to clean up.
Helper files: a small script (gen.mjs) that does the mail-merge, and a template.html that holds the fixed visual shell. The skill itself only ever writes the *content* — the look is pre-built and reused. That's the "separate content from shell" idea, made real.

5. How YOU could build your own

You don't need the fancy version. Here's the minimum:

List the questions a future-you would ask. For a handoff: What's done? Where do things stand? What's the very next step? What's broken or weird? Those become your fixed sections.
Write a skill that fills in those sections from the conversation — just a text file telling the agent "when I say wrap up, collect these things and write them to a file."
End the file with a restart line. One sentence: "To continue, do X first." That single line is what makes it self-sufficient.
Add a trigger phrase to the description so the agent offers it on its own — "use when wrapping up or switching tasks."

That's a working handoff. The template and script are polish you add later.

6. When to use it — and when NOT to

Use it when: a session is ending with unfinished work, context is getting full, or you're switching projects and want a clean restart point.
Skip it when: the task is already done and shipped (nothing to continue), or the session was trivial. A handoff for "we changed one word" is just noise. Don't pad.

7. The stripped-down version

This is a complete, working handoff skill. Paste it, change the words, done:

---
name: handoff
description: Save session state to one file for a clean restart. Use when wrapping up, context is full, or switching tasks.
---

# Handoff

When I signal we're wrapping up, write a file called HANDOFF-<topic>-<date>.md with:

- DONE — what got finished (be specific: files, results)
- NOW — where things stand right now (what's running, what's deployed)
- NEXT — ordered next steps; item 1 is the very next thing to do
- GOTCHAS — anything weird or broken the next session must know
- RESTART — one sentence telling the next session what to do first

Then show me the file path. Keep it specific — paths and facts, not vague summaries.