claude-handoff hands the current conversation to a fresh background agent that picks up the work straight away. It writes a handoff summary, saves it to your computer's temporary folder, then starts the new agent with claude --bg, using that summary as its prompt. The command returns at once, and you manage the new agent with claude agents.
When to use it
The work should carry on now, in a new Claude Code session, while you keep this one.
The next agent can start where you are: it starts in the current working directory.
It's user-invoked: an agent never loads it on its own. You type /claude-handoff, and you can add what the next session will be used for, so the summary is shaped around that.
When not to use it
You want a file to carry on from later, in another agent tool (a harness), or to give to a colleague. That's handoff: it writes the same kind of summary as a document, and starts nothing.
You only need room in this session. /compact swaps this session's history for a summary, and you carry on from it: same harness, same directory, and you stay in the loop.
You want to give the whole job to an agent in another Orca worktree. That's orca-cli: a full handoff moves ownership to the other agent, and the first one stops.
What it needs to start
A conversation worth carrying on.
Claude Code, which runs the background agent.
A descriptive name for the new agent, such as "Fix login bug". It shows in the job list, the session picker and the terminal title.
What it creates
A handoff summary in the OS temporary folder. It has a "suggested skills" section, naming the Skills the next agent should load. It points at Specs, Issues and commits by path or URL instead of copying them. And it leaves out API keys, passwords and personal details, since the summary becomes the agent's prompt.
A named background agent, seeded with that summary and listed in claude agents.
Going deeper
6 min read · Going deeper not read
Why it exists
Matt opened pull request #421 on 2 July 2026, adding claude-handoff to his in-progress bucket. The pull request calls it "Identical to the existing handoff skill, with one substantive difference": instead of saving the summary to a Markdown file, it hands the summary straight to a fresh background agent as its first prompt. The file part is out of date. Pull request #1185 (6 October 2026) added a file step, and the current SKILL.md, at the 29 October 2026 commit, says "Save it to the temporary directory of the user's OS". SKILL.md is the newer source, so it saves the summary as a file too. What still sets it apart is that it starts the new agent.
Matt's in-progress README, at the 29 October 2026 commit, opens with "Beta." and says its Skills "can change or disappear without warning". They're left out of the plugin and get no docs pages, so you install this one on its own.
Matt's plans for it are still moving. On 23 July 2026 he opened pull request #647, which would replace it with a generic spawn Skill that could also start Codex, Cursor and other agents. The same day he commented "Closing — rethinking whether a generic spawn skill makes sense." Yet on 30 October 2026 that pull request is still open and unmerged. So the current SKILL.md, at the 29 October 2026 commit, is what claude-handoff does.
From snapshot/skills/claude-handoff/SKILL.md, line 8: “Write a handoff summary of the current conversation so a fresh agent can continue the work. Save it to the temporary directory of the user's OS, then launch a background agent seeded with it as its prompt:”
Matt's AI Coding Dictionary describes a handoff as moving an agent's context from one session to another. The receiving session "starts with zero context". And there's "No return path": the new session can't ask the old one what it meant, so the summary has to stand on its own.
The carry can take more than one form, and he compares two of them in a table. A handoff artifact is a file: "You can read and correct it before anything depends on it". Compaction is a summary inside the context window: it's "Automatic and cheap; harder to inspect; feeds one successor". In claude-handoff, the summary is saved as a file, and the same text becomes the new agent's prompt:
claude --bg --name "<descriptive name>" -- "$(cat <summary file>)"
Passing the file keeps the shell from running backticks or expanding $ in the summary. The -- stops a summary that starts with - being read as an option.
On the Claude Code side, a background session is "a full Claude Code conversation that keeps running without a terminal attached". It starts in your working directory. Before it edits files, Claude Code moves it into its own git worktree under .claude/worktrees/, so parallel sessions can read the same checkout but each writes to its own. That step is skipped when the session is already inside a git worktree: then it edits that worktree. claude agents opens agent view: one screen for what's running, what needs your input, and what's done. A session shows "Needs input" when it's waiting on something only you can provide, such as an answer to a question.
Agent view, opened with `claude agents`: background sessions grouped as Needs input, Working and Completed. From code.claude.com, 30 October 2026.
It starts in your working directory.
its own git worktree under .claude/worktrees/That step is skipped when the session is already inside a git worktree
Needs input
what's done
a full Claude Code conversation that keeps running without a terminal attached
A real example
The launch line looks the way it does because of a real bug. Issue #562, opened on 14 July 2026, reported that the Skill put the summary straight into the command, inside double quotes. A summary can hold backticks and $, and the shell ran or expanded them. Nothing crashed. The reporter's example: a summary saying "We changed src/auth.ts to fix the bug" reached the agent as "We changed to fix the bug". The background agent just started with less context than it should have had.
Pull request #1185 (6 October 2026) changed the launch line to the one in today's SKILL.md. The summary is now written to a temporary file and passed as "$(cat <file>)" after --, because the shell doesn't re-read the output of $(cat ...). Its before-and-after test shows src/auth.ts and $HOME arriving intact.
Where it goes wrong
Questions split across two sessions. Issue #1307 (20 October 2026) reports a summary that told the background agent to "put the open questions to the user and wait". The user answered in the main session, and the main agent had to relay those answers to the background agent. The reporter's root cause: the background agent is out of your line of sight, so any question it asks splits the decisions across two sessions. Their suggested fix, still open: keep open decisions in the session you're talking to, and brief the background agent to build things only.
A thin summary. Matt's dictionary says "The visible failure of a bad handoff is relitigation": the new session re-opens decisions the old one had settled, because the summary recorded what was decided but not why. Like /compact, a handoff gives the new agent a summary in place of the session itself, and a summary is lossy.
A different model. Issue #562 also pointed out that without --model, the background agent uses the CLI default, not the model from the current session. Pull request #1185 left that out on purpose, and the current SKILL.md still doesn't pass --model.
The name blocks Claude Cowork. Issue #728 (3 August 2026) reports that Cowork rejects the whole plugin, because two Skills' names contain the reserved word "claude", claude-handoff's among them. That happens even though the plugin doesn't ship it. The issue is still open.
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't), install it on its own with npx skills@latest add mattpocock/skills --skill=claude-handoff. Then, in a Claude Code session started from your yoga-studio repo's main checkout (not from inside a worktree), talk through an api/ endpoint that cancels a booking and settle every open decision there. Run /claude-handoff write the failing test for cancelling a booking, then make it pass, and watch its new row in claude agents. When it's done, check that it worked in its own worktree under .claude/worktrees/.
From snapshot/skills/handoff/SKILL.md, line 8: “Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS”
From snapshot/skills/ask-matt/PHASE-BOUNDARIES.md, lines 27–34: “/handoff is narrow. You need it only when you are: - swapping to a new harness (Claude → Codex), - moving to a new directory or repo, - sending the work to a colleague,”
From snapshot/skills/claude-handoff/SKILL.md, line 10: “Always pass -n/--name with a descriptive name (e.g. --name "Fix login bug"); it sets the display name shown in the job list, session picker, and terminal title.”
From snapshot/skills/claude-handoff/SKILL.md, line 14: “Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.”
From snapshot/skills/claude-handoff/SKILL.md, line 16: “Redact any sensitive information, such as API keys, passwords, or personally identifiable information, since the summary becomes the agent's prompt.”
From snapshot/web/github.com/mattpocock-skills-pull-1185.md, lines 19–22: “-Instead of saving it, launch a background agent seeded with the summary as its prompt: -claude --bg --name "<descriptive name>" "<handoff summary>". +Save it to the temporary directory of the user's OS, then launch a background agent seeded with it as its prompt:”
From snapshot/web/github.com/mattpocock-skills-pull-421.md, line 16: “Identical to the existing handoff skill, with one substantive difference: instead of saving the conversation summary to a markdown file, it hands the summary straight to a fresh background agent as its seed prompt”
From snapshot/skills/claude-handoff/SKILL.md, line 8: “Save it to the temporary directory of the user's OS, then launch a background agent seeded with it as its prompt: claude --bg --name "<descriptive name>" -- "$(cat <summary file>)". Passing the file keeps the shell from running backticks or expanding $ in the summary.”
From snapshot/web/code.claude.com/docs-en-agent-view.md, line 464: “When you dispatch a background session from agent view or start one with claude --bg, the session starts in your working directory. Before editing files, Claude moves the session into an isolated”
From snapshot/web/github.com/mattpocock-skills-issues-562.md, line 20: “A handoff summary can contain backticks, $(...), $VAR, and quotes. When that text is interpolated into a double-quoted shell argument, it is not treated as plain text. The common failure mode is not a crash, but silent truncation:”
From snapshot/web/github.com/mattpocock-skills-pull-1185.md, line 16: “Closes #562 (point 1 only). claude-handoff put the summary straight into a double-quoted shell argument, so backticks, $(...) and $VAR ran or expanded and the background agent got a silently truncated prompt.”
From snapshot/web/github.com/mattpocock-skills-issues-1307.md, line 30: “I answered in the main session ("all as recommended"). The main agent had to relay my answers to the background agent via SendMessage (two relay rounds), so it would not re-ask questions that were already settled.”
