handoff

How it is organised

What’s inside

The skill’s top-level sections, in order. The bar is each section’s share of the 1,646 words, so you can see where the weight sits before reading.

1. 1When to write one109 words
2. 2Before you write125 words
3. 3What goes in it630 words
4. 4Redaction104 words
5. 5Where it goes155 words
6. 6Report63 words
7. 7Picking one up153 words
8. 8Example101 words
9. 9Common mistakes119 words

The skill itself

Read it before you install it

---
name: handoff
description: Write a handoff so a fresh session, another agent or a person can continue unfinished work without re-deriving it: the goal, what is done and what is not, decisions and why, what was tried and failed, what was checked versus assumed, and one exact next step. Use when the user says "hand off", "write a handoff", "wrap up", "save state", "I'm running out of context", "we'll continue later" or "pass this to another agent", or is about to clear the session or switch tool, branch or machine mid-task. Also covers resuming from a handoff and checking it against the repository's live state. Not for finished work (the commit and pull request record that), not for delegating a task to a worker, and not for summarising a conversation for its own sake.
license: MIT
---

# Handoff

A handoff carries unfinished work across a gap: a cleared session, a different tool, another agent, another person, another day. The reader has none of this conversation, so the document is all they get. It should let them start work at once and trust what they read. It is a launchpad, not a transcript.

## When to write one

- The user asks, or is plainly about to lose context: stopping for the day, clearing the session, switching branch, tool or machine, blocked on a decision, or passing the work to someone.
- Skip it when the work is finished. The commit, the pull request and the changelog record that. If finished work is still uncommitted, say so and leave committing to the user.
- Skip it when the session produced nothing the next one needs, such as one question answered. Say that instead of writing filler.
- A handoff does not replace committing. Never commit, push or publish on the user's behalf to make a handoff tidy.

## Before you write

1. If the user has not said what the next session is for, ask once. A handoff for "finish the migration" and one for "review what I did" are different documents. Keep what serves that focus and cut the rest.
2. Check the facts you are about to state against the machine, not against memory. In a repository, look at the current branch, the latest commit, the changed and untracked files, and whether any pull request you mention has since merged. After a long session, or alongside other sessions, the disk is often ahead of your recollection. Use read-only commands. When the real state contradicts your memory, the real state wins.
3. Outside a repository, say so and list the relevant files by absolute path.

## What goes in it

Use these sections in this order. Leave out any with nothing real to say, or write "None." Never pad, and never invent an entry to fill a section.

1. **Title and header.** One line naming the work, then the date (absolute, never "yesterday"), working directory, branch, short commit, and the focus of the next session.
2. **Next step.** Exactly one concrete first action: a file to open, a command to run, an edit to make. "Continue implementing X" is not a next step. Follow it with a short ordered list.
3. **Goal.** What the work is for, in one or two sentences, and what it will not do.
4. **State.** What is done, in progress and not started, naming files. Half-finished is a legitimate answer and more useful than a summary that rounds up. Separate saved from unsaved: list what is committed (and whether it is pushed), then every uncommitted or untracked path in full. A reader who cannot see that line will treat working-tree edits as safe.
5. **Decisions.** One line each: the choice, the reason, and who made it, the user or this session. Never record a decision the user made as a shared one. Include decisions that were reversed, and why, or the next session will argue them again.
6. **Tried and failed.** Approaches abandoned and the reason. Nobody can reconstruct this from the repository, and it is the part most likely to be repeated at full cost.
7. **Checked and not checked.** For each "works" or "fixed", give the command or observation and its result: "the suite passes: ran the test command, 41 passed, 0 failed". A claim with no such backing goes under open questions. Say plainly what was not run. Label any claim you inherited from an earlier handoff and did not re-check as inherited. A claim passed along with growing confidence and never re-measured is the riskiest line in a handoff.
8. **Blockers and open questions.** What is waiting, on whom, and what would unblock it.
9. **Constraints and permissions.** The user's rules ("don't touch the schema", "ask before deploying") and what has and has not been authorised.
10. **Pointers.** Specs, plans, decision records, issues, pull requests, commits and key files, by path, URL or identifier, each with a clause on why it matters. Reference, do not copy. Prefer a function, type or heading name to a line number, which moves.
11. **Still running.** Servers, watchers or jobs you started that are still up, and how to stop them. Do not stop anything you did not start.
12. **Suggested skills.** Only skills the next session is likely to have, each marked "if available" with a reason.

Some rules apply throughout:

- **Reference, do not duplicate.** Anything already captured in a spec, plan, decision record, issue, commit or diff is cited by path or URL, with one line on why it matters.
- **Unsaved work does not travel.** Uncommitted changes, unpushed commits and untracked files will not exist for a reader on another machine. Inline only the fragment that carries a decision (a schema, a type shape, the few changed lines that matter), never a whole diff.
- **No invented facts.** Do not make up paths, commits, counts or results. Write "unknown" where something should be known and is not, and "not decided" where the question never got answered.
- **Facts about the environment go stale.** For "it is deployed", "the service is up" or "the other repo has no remote", give the date and the command that re-checks it.
- **A failing test is state, not a task.** Record its name and output. Do not start fixing it as part of the handoff.
- **Keep it short.** A page or two usually does it. If it reads like a meeting recap, cut it.

## Redaction

The handoff may be pasted into a prompt, shared, or left in a folder, so treat it as public.

- Never copy a key, token, password, private key, connection string, `.env` value, or a URL with credentials in it. Name the variable, not its value.
- Leave out personal data about people who are not the user.
- Say what you redacted and where ("the database password, used by the seed script"), so the next reader knows a value exists instead of inheriting a silent gap.
- After writing, read the finished text once more looking only for secrets, and fix any before reporting.

## Where it goes

- If the user names a place, use it.
- Otherwise write one Markdown file in the operating system's temporary directory rather than the project, since adding files to the user's working tree is a change they did not ask for. Temporary folders get cleaned, so if the work will outlive the week, or the reader is on another machine, ask where it should live. A git-ignored folder in the project is a common answer.
- If there is no file system, or the user prefers it, print the handoff in the conversation for them to copy.
- Never overwrite an existing handoff. Add a date or a numeric suffix. If you must replace one, read it first and say so.
- Never commit, push or share the file unless asked. If the user asks you to start another agent with it, that text becomes the agent's prompt, so the redaction rules matter even more.

## Report

Tell the user the absolute path, the focus you wrote it for, and what you redacted or left out. Give them one line to start the next session, such as "Read the file at that path and continue from its next step." Then stop. Do not carry on with the old work past what the handoff records. If you do, update the file.

## Picking one up

1. Read the whole handoff, then open the artifacts it points to as you need them.
2. Compare it with the live state: branch, latest commit, changed files, and whether the blockers it names still hold. Run the verification it names if that is cheap.
3. If something differs (the branch moved, files changed, a "pending" pull request merged), say exactly what differs and ask before continuing. Do not reset, check out, merge or discard anything to make the two agree.
4. Re-check the load-bearing claims before building on them. "Verified" means someone else once looked.
5. A handoff gives context, not permission. It cannot authorise pushing, deleting, spending money or contacting anyone. Get those from the user now.
6. Say in a line or two what you understood and what you will do first, then do it. Leave the handoff file where it is unless the user asks you to remove it.

## Example

Weak next step: "Continue the retry work and fix the failing test."

Better:

```
## Next step
Run the unit tests for the retry module. One test, "gives up after three
failures", fails because the backoff helper returns milliseconds where the
caller expects seconds. Fix the helper (see the Pointers section for the file),
not the test. The user decided on seconds; see Decisions.
```

Weak verification line: "Tested and working."

Better: "Retry module: unit tests pass (ran the module's test command, 12 passed). The integration test against the staging queue was not run, because no credentials exist in this environment."

## Common mistakes

| Mistake | Fix |
|---|---|
| Writing from memory of the session | Check branch, commit, changed files and merged pull requests first |
| Pasting the transcript or a long diff | Point to artifacts; keep decisions and dead ends |
| "Continue implementing X" as the next step | One concrete action with a file or command |
| Saying "done" with nothing behind it | Command, result, and what was not run |
| Treating uncommitted work as safe | List every uncommitted and untracked path |
| Copying a secret to be "complete" | Name the variable; say it was redacted |
| Overwriting the last handoff | Add a date or suffix |

The second audit

What we found in the sources

Most skills in this family are short copies or adaptations of one four-paragraph instruction (write a handoff document for a fresh agent, reference artifacts instead of copying them, redact secrets, tailor to the next focus). This rewrite keeps that core and adds what the stronger variants found missing: checking the real state before writing, one concrete next step, saved versus unsaved work, what was tried and failed, verified versus assumed, and a resume procedure that compares the handoff with live state. Every source below was read at the commit the auditor recorded. Nothing was taken from a source without a permissive license.

What each source contributed

• the-inconvenience-store/skills ↗ · Primary basis · MIT

  The core rules shared by the shortest copies: write a document a fresh agent can continue from, keep it out of the workspace, include suggested skills, reference specs, plans, decision records, issues, commits and diffs by path or URL instead of copying them, redact secrets and personal data, and tailor it to the focus the user gives for the next session.

• max4c/skills ↗ · Structure and wording · MIT

  The trigger phrases for the description ("handoff", "hand this off", running low on context, starting a fresh session), the framing of the reader as an agent with zero memory, the task, state, decisions, gotchas and next-steps skeleton, the split between verified, assumed and untested, and the launchpad-not-transcript test.

• blauwtje/exo ↗ · Added ideas · MIT

  Pointers instead of pasted content; separating saved from unsaved work by reading the repository status and listing every uncommitted path; exactly one next step; a proven-claims line that names the command and its result; marking a decision as the user's or the session's; and the point that a handoff pasting the transcript back wastes the context a clear just freed.

• kopfwelt/skills ↗ · Added ideas · MIT

  Demoting unchecked claims to assumptions, writing down failed approaches, redacting and then re-reading the finished text for secrets, asking what the next session is for, the distinction between a handoff and compacting, and the argument that temporary directories get cleaned out.

• ziazon/zizi-skills ↗ · Added ideas · MIT

  Re-checking git and pull request state before writing because chat memory runs behind the disk; labelling claims inherited from an earlier handoff and re-measuring the load-bearing ones; stating the verification method rather than only the result; dating environment claims and giving the command that re-checks them; recording how a working system breaks; an inventory of processes the session started (changed from stopping them to listing them); never overwriting a handoff that has not been read; converting relative dates to absolute ones.

• joesys/joesys-skills ↗ · Added ideas · MIT

  The resume flow that compares the handoff with live repository state and stops on drift instead of reconciling it; the rule that a handoff cannot grant new permission to push, delete or publish; treating only commands actually run as evidence; distinguishing unknown from not decided; never overwriting an existing handoff; never committing or sharing it automatically.

• jcottam/agent-resources ↗ · Added ideas · MIT

  Skipping a handoff when nothing is left to continue, a do-not-redo list of failed approaches, a verified-facts versus assumptions split, the resume step of restating the goal and first step and then acting, and warning when the repository has moved since the handoff was written.

• oprogramadorreal/optimus-claude ↗ · Added ideas · MIT

  Sorting artifacts by whether they exist on the remote and inlining only the unpushed or untracked fragments that carry a decision; trusting repository state over chat memory when they conflict; the classes of secret to redact (keys, tokens, passwords, connection strings, secret files by variable name only); re-reading the written file for secrets; never committing the handoff itself.

• marinvch/Cortex ↗ · Added ideas · MIT

  Saying what was redacted and where so the next agent knows a value exists, the rule that a handoff is not a substitute for committing, and naming the branch and working-tree state.

• xu91102/claude-everything-Workflow ↗ · Added ideas · MIT

  Writing only on the user's explicit request, using a private file and never overwriting an existing path, marking uncertainty instead of inventing facts, reporting the path together with anything omitted or redacted, and not continuing the old work after returning the handoff.

• agentwolf27/claude-skills ↗ · Added ideas · MIT

  Treating what was tried and did not work as the most valuable paragraph, accepting half-finished as an honest state, naming the blocker, and saying what was not checked.

• borkweb/skills ↗ · Added ideas · MIT

  Writing "None." under an empty section instead of padding or inventing, leading with next steps, and a fixed section order.

• sabilmakbar/claude-session-kit ↗ · Added ideas · MIT

  Recording decisions that were reversed, and why, so the next session does not relitigate them, and stating open work as its exact current state.

• iuripereira/deltaspec ↗ · Added ideas · MIT

  Writing a record only for a session with real progress (a one-off question gets no file), keeping intent and progress rather than what the next session can read from the code, and ending with a one-line prompt to start the next session.

• SukbeomH/HExoskeleton ↗ · Added ideas · MIT

  The rule that a failing test at handoff time is recorded with its output and passed on, not fixed as part of wrapping up. This source is in Korean; I read it in full.

• jiahao-shao1/sjh-skills ↗ · Added ideas · MIT

  Printing the handoff in the conversation for the user to paste into the next session, and asking the user to fill gaps when the context is not enough.

• ananthanandanan/skills ↗ · Added ideas · MIT

  The rule never to invent paths, line numbers, commits or counts, and to omit them when unsure.

• rengwu/wayfinder-maps ↗ · Added ideas · MIT

  Marking suggested skills as applying only if the next agent has them, and the fallback of the temporary directory when there is no repository.

What changed

• The description now lists the phrases a person would type ("hand off", "wrap up", "save state", "I'm running out of context", "we'll continue later") and a not-for clause. Most sources describe the skill in one line with no phrases.
• Rewritten as one self-contained file with no references to companion scripts, templates, other skills, plugin namespaces or a particular agent harness.
• The sources disagree on where to write the file (the OS temporary directory, a committed .plan folder, docs/, .handoffs/, .claude/handoffs/, a path under the git directory, the conversation). The rewrite defaults to a file in the temporary directory so the user's working tree is not changed unasked, says that temporary files get cleaned, asks where to put it when the work will outlive that, and allows printing it in the conversation. This is a judgement, not a tested choice.
• The sources also disagree on whether to check the repository before writing (ziazon, optimus, exo say yes; ananthanandanan says do not re-read anything when context is nearly full). The rewrite checks with read-only commands and lets the real state win over memory.
• Added a resume section that compares the handoff with live state and asks before continuing on drift. Only a few sources cover resuming at all.
• Anything that acts on the user's repository (committing, pushing, pruning, killing processes, archiving a session) was removed or made conditional on the user asking.
• Dropped numeric limits on length. Where a source gave one it gave no basis. The rewrite says a page or two usually does it and to cut if it reads like a meeting recap.

Problems found in the sources

• !mattpocock/skills: The claude-handoff variant launches a background agent with a specific command-line tool and passes the summary as the agent's prompt, so it only works in that host, and the summary becomes a prompt, which makes its redaction line load-bearing. Its content rules are four short paragraphs.
• !the-inconvenience-store/skills: The handoff file is four short paragraphs. Its description is one line with no trigger phrases. It tells the agent to save to the OS temporary directory, which other sources argue gets cleaned out. Its claude-handoff file has the same bytes (same SHA-256) as the one in mattpocock/skills.
• !CapitalCantrip/quality-gates: Byte-identical (same SHA-256) to Bossmann007/cursor-kit. It tells the agent to name which skills the next agent should "call the Skill tool for", a tool name that only some hosts have.
• !rengwu/wayfinder-maps: Same four paragraphs, but it saves into a committed .plan/handoffs folder and, if there is no repository, the temporary directory, so the family disagrees on where a handoff goes.
• !max4c/skills: No defects found beyond OS-specific path hints ($TMPDIR on macOS, /tmp as fallback). Its description has explicit trigger phrases, unlike the shorter copies.
• !blauwtje/exo: Replaces any handoff already at the target path without asking (it says the old state is what the clear discards; unclear whether that is intended as a choice). Refers to a planning skill and a /clear command that are not in the file, and fixes a path under the git directory.
• !kopfwelt/skills: Depends on scripts/new-handoff.sh, references/document-template.md and a companion wip skill, none of which are in the downloaded file.
• !ziazon/zizi-skills: About 33 KB, much of it tied to one author's setup: a LOCAL.md file beside the skill, git-sync, done and status-update skills, resume chips, a vault note and an archive-session call. It instructs force-killing processes by port, pruning merged branches and worktrees, and pushing a learnings file immediately, with no confirmation step. It states a "60-90s per-tool latency" for two tools it rejected, with no method given. The advice on checking real state, inherited claims and stale environment claims is concrete and is where most of its value lies.
• !joesys/joesys-skills: Depends on helpers/handoff_state.py, two reference files and a ../shared/report-style.md that are not in the downloaded file, and uses Codex-style $handoff invocation. The drift classification (exact, advanced, drifted, unverifiable) is computed by the missing helper.
• !jcottam/agent-resources: Refers to scripts/workspace-id.sh, which is not in the file, writes under a fixed ~/.agents/handoffs/ folder, mentions Cursor project folders and a cursor-chat source, and states a budget of 120 lines (about 2,500 words) with no basis.
• !oprogramadorreal/optimus-claude: Uses a question tool, a $CLAUDE_PLUGIN_ROOT reference file and a /optimus: command, so a lone copy has dangling references.
• !marinvch/Cortex: Adds rituals specific to that project (/dream, /catch-me-up), a vault, and an employer-firewall rule. It credits mattpocock/skills as the upstream of the instruction body.
• !xu91102/claude-everything-Workflow: Points the fresh session at skills/using-superpowers/SKILL.md, which is not in the file, and tells it to delete the handoff and its directory. It credits mattpocock/skills at a pinned revision as its origin.
• !agentwolf27/claude-skills: Depends on a local Pulse plan tool, PLAN.md, PROGRESS.md and TASKS.md, and a house-files skill for templates, and uses inline shell-command syntax in the skill text.
• !borkweb/skills: Fixes exactly eight headings, which is a choice; unclear whether it suits human readers as well as agents. Includes a paragraph specific to Codex runs and agent ids.
• !iuripereira/deltaspec: The body is in Portuguese although the bundle labels it English. It is built around that project's own records (debts registry, ADR numbers, python scripts via a plugin root), so it is not usable on its own.
• !SukbeomH/HExoskeleton: Korean. Its iron laws include "no session end without a git push" and a commit step, and it calls scripts and a commit skill from its own repository. Pushing without asking the user is unsafe as a default.
• !sabilmakbar/claude-session-kit: Two modes (bundle for another machine, split a session) that rely on shell scripts under a home folder and a hook. If the scripts are missing, the skill says to report that and not work around it.
• !jiahao-shao1/sjh-skills: 698 bytes and prints a seven-heading summary. It says nothing about redacting secrets.
• !ananthanandanan/skills: Writes into docs/ inside the workspace by default, which contradicts the temporary-directory sources, and tells the agent not to re-read files or run a self-check because context is nearly exhausted. Unclear whether that is a flaw or a deliberate trade-off. Refers to skills with an ank: prefix and lists allowed tools in its front matter.
• !thewinci/local-rag: Its steps call three tools that belong to that project's own server, so it cannot run elsewhere.

What was dropped

• The launch of a background agent through one command-line tool (mattpocock/skills claude-handoff). The rewrite only mentions that any text used as an agent's prompt needs the same redaction.
• Committing and pushing as mandatory steps (SukbeomH/HExoskeleton), force-killing processes by port, pruning merged branches and worktrees, and archiving the session as the final action (ziazon/zizi-skills). None asks the user first.
• Cross-machine session bundling, session splitting and the hook that surfaces pending handoffs (sabilmakbar/claude-session-kit); they depend on shell scripts that are not in the skill file.
• Front matter with a YAML schema, a workspace-id script and a latest-copy convention (jcottam/agent-resources); they depend on a script that is not in the file and a fixed folder in the home directory.
• Obsidian vault refreshes, resume chips, per-skill learnings sweeps, model recommendation lines and a skills review (ziazon/zizi-skills); specific to that author's setup.
• The multi-repo detection, plugin commit command and interactive enhance-or-overwrite prompt (oprogramadorreal/optimus-claude); they depend on that plugin and a question tool.
• Codex-specific instructions about agent liveness and run ledgers (borkweb/skills).
• The instruction for the fresh session to delete the handoff and its directory after use (xu91102/claude-everything-Workflow). The rewrite leaves removal to the user.

Same text, wherever you work

Use it where you work

git clone https://github.com/nikbearbrown/skills
cp -R skills/skills/handoff ~/.claude/skills/

Pairs with