handoff writes a handoff document: one Markdown file that sums up the current conversation, so a fresh agent can carry on the work somewhere else. What it buys is portability: a file that travels.
When to use it
It's narrow. Use it only when the work is travelling:
to a new harness, the agent tool you run (say, from Claude Code to Codex);
to a new directory or repo;
to a colleague;
or a side task you noticed mid-way, split off without derailing what you're doing.
In the Main flow, it bridges the prototype detour both ways. A prototype lives in its own directory, so you hand off out, build the prototype in a fresh session, then hand off back what you learned.
hand off out
build the prototype in a fresh sessionA prototype lives in its own directory
hand off back what you learned
In the Main flow, it bridges the prototype detour both ways.
When not to use it
Nothing is travelling. If the next step needs this session as it happened, just carry on in it: the next step wants the reasoning word for word, not a summary. That's why the interview, the Spec and the Tickets all stay in one session, building on the same thinking.
You want the whole feature written down for the team to build: that's to-spec, which publishes a Spec to the issue tracker. A handoff document is a temporary note for the next agent, not a Spec.
Every move except carrying on swaps the session itself (a primary source) for a summary of it (a secondary source), and a summary loses detail. So rule out carrying on first.
What it needs to start
A conversation worth carrying on. You can also say what the next session will be for, and the document is shaped around that.
What it creates
One Markdown file, saved in your computer's temporary folder ($TMPDIR, else /tmp), not in the repo. It:
sums up the conversation so far;
has a "suggested skills" section, naming the Skills the next agent should load;
points at anything already written down, such as the Spec, ADRs, Issues or commits, by path or URL, instead of copying it;
leaves out secrets: API keys, passwords and personal details.
Going deeper
5 min read · Going deeper not read
Why it exists
Matt's video of 21 May 2026 tells the story. He found /compact really useful for long single sessions, but "I wanted to compact into another session." Say he spots a refactoring job mid-session, out of scope for the work he's on. Carrying on would leave "diluted context". Compacting "would clobber all of the progress" he'd made. So he kept asking the agent for a handoff.md to pass to another agent, and "I was doing this so freaking often that I just decided, 'Okay, I need a skill for this.'"
His changelog post of 11 May 2026, which announced it, gives the same problem: "you're deep into a grilling session at 60K tokens, and you need to prototype something or fix a bug." He named two patterns, "fire and forget" and "DIY sub-agent". He put it in the productivity section of his repo, "because it's useful beyond just engineering work".
Matt has since narrowed the pitch. His Skill page, updated 24 August 2026, puts it this way: "What it gives you is portability, not compression". His version 1.2.0 CHANGELOG entry agrees: "/handoff was oversold. It read as the general bridge between context windows." This newer framing is the one to follow. The current SKILL.md still does the same job the May video showed.
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 ($TMPDIR, else /tmp; %TEMP% on Windows) - not the current workspace.”
From snapshot/skills/ask-matt/PHASE-BOUNDARIES.md, lines 27–34: “3. Do you need to hand off?/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, - or forking a side task you found mid-phase without derailing what you're doing. That list is the whole clause. What /handoff buys is portability: a file that travels. If nothing is travelling, you don't need it.”
The icon at the top of Matt's page for the Skill, updated 24 August 2026. From aihero.dev, 30 October 2026.
How it works underneath
The document is plain Markdown, so any agent tool can read it. In the video Matt says the first session can be Claude Code, and "you can just pass this to another agent", such as Codex or Copilot CLI.
The use people skip, Matt's page says, is the fork. "You stay in your session and hand a copy of the accumulated context to a second agent working in parallel." He calls the round trip a DIY sub-agent: you hand off, the second session does the work, then it hands its learnings back.
How is that different from just forking the session? "A fork inherits an exact copy of the context; this skill produces a targeted compression aimed at a stated next task, in a file." That's why the next session's purpose matters so much. Matt: "Every time I used handoff, I always describe the purpose".
The page also sets it against the built-in commands. Each one preserves something different. /compact preserves your intent, /clear preserves nothing, /handoff preserves the work's ability to move.
/compact
/clear
/handoff
preserves your intent
preserves nothing
preserves the work's ability to move
Each one preserves something different.
The agent never starts it on its own. The SKILL.md front matter sets disable-model-invocation: true, and its Codex settings set allow_implicit_invocation: false, which the CHANGELOG calls "the Codex analog" of that line. You type /handoff yourself.
A real example
In the video, Matt is grilling plans for Sandcastle, his "software factory". At question 2 he says the iterations and the completion signal may move to a separate API: "let's hand off that task to a separate agent." Saying it was out of scope sharpened the grilling too: "Q2 collapses". The handoff file asked the next session to file a GitHub issue, and later he passed it to another agent to do that.
In another grilling session, at question 13, he hands off "to prototype the difficult bits". That prototype session grew to "169 K tokens, so way bigger than would have fit inside the grilling." Then he asked for a handoff back: "Take all of the learnings from the prototype, anything that's not directly captured in the prototype itself or that's non-obvious". With those, he finished the grilling and wrote the PRDs and issues.
Where it goes wrong
The file lands somewhere different each time. Issue #272 (29 May 2026): on Windows "it took Claude 3-4 attempts to locate the temp location". On 26 June another user added that on a Mac, "on 3 separate runs, the skill created files in three separate places". Matt's fix, shipped in 1.3.2, names the folder in SKILL.md ($TMPDIR, else /tmp; %TEMP% on Windows), "so agents stop guessing". Matt's page (updated 24 August 2026) calls the temp folder "the most-reported problem with the skill", and says: "Ask for the path back and keep it before you move on."
The file vanishes. "Some environments clear temp between sessions (Codex is the reported case), and a reboot empties /private/tmp." If the next session isn't starting within the hour, copy the file somewhere durable.
The brief gets cut short. Pasting the summary into claude "<summary>" can break on backticks or $(...). "The usual result is silent truncation rather than an error". Point the new session at the file's path instead.
A guess becomes a fact. "The next agent trusts the document and does not re-check it, so a belief written as a fact becomes a false premise for everything that follows." Read the document before handing it over, "and downgrade anything you only assumed."
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't), fork a side task off a working session.
Start a session on the booking endpoint in api/. Partway in, pick something out of scope, such as the web/ site's build being slow.
Type /handoff fix the slow web/ build in a fresh session. The words after the command tell it what the next session is for.
Ask for the file's path. Check the file: Issues and commits appear as links, not copies; there's a suggested skills section; there are no secrets. Change any claim the session never checked into "not checked".
Copy the file into a folder that survives a reboot.
Open a fresh session and say: "Read this file, then continue." Then go back to the first session. It should be unchanged.
Going deeper's Check questions are asked in Next up.
“detour through a prototype, bridged by /handoff in both directions (a prototype lives in its own directory, which is exactly what /handoff is for; see Phase boundaries): - /handoff out, then open a fresh session against that file, - /prototype to answer the question with throwaway code, - /handoff back what you learned, and reference it from the original idea thread.”
From snapshot/skills/ask-matt/PHASE-BOUNDARIES.md, line 21: “Grilling → implementation is the standard yes: the implementation wants the reasoning verbatim, not a summary of it. Continue costs nothing and loses nothing, so rule it out before anything else.”
From snapshot/skills/handoff/SKILL.md, line 16: “If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.”
From snapshot/skills/handoff/SKILL.md, line 10: “Include a "suggested skills" section in the document, naming which skills the next agent should call the Skill tool for.”
From snapshot/skills/handoff/SKILL.md, line 12: “Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.”
From snapshot/web/youtube.com/watch-v-dtaj2dod3ko.md, lines 59–61: “So, I continue to find compact a really, really useful tool for creating these long single sessions. [04:54] But what I started to notice was I wanted to do other things with compact. [04:58] I wanted to compact into another session.”
From snapshot/web/youtube.com/watch-v-dtaj2dod3ko.md, lines 71–74: “Write me a handoff.md document so that I can then just pass that into another agent." [06:07] And it turned out I was doing this so freaking often that I just decided, "Okay, I need a skill for this."”
From snapshot/web/youtube.com/watch-v-dtaj2dod3ko.md, lines 108–110: “the thing that's cool about just using like a markdown documents here and not relying on kind of native agent stuff is that you can have this first session be [09:33] Claude code, but you can just pass this to another agent, right? [09:35] You can pass it to Codex or pass it to, you know, Copilot CLI, whatever you're using.”
From snapshot/web/aihero.dev/skills-handoff.md, line 154: “The fork case is the one worth knowing. You stay in your session and hand a copy of the accumulated context to a second agent working in parallel.”
From snapshot/web/youtube.com/watch-v-dtaj2dod3ko.md, lines 102–105: “you hand off to another session, that session then creates another handoff [08:53] document, and then passes it back to the original session. [08:55] It's almost like you've done a kind of DIY sub-agent”
From snapshot/web/youtube.com/watch-v-dtaj2dod3ko.md, lines 78–80: “I'm only in Q2 of this grilling session, so not a long one. [06:30] And I say here, "I think in future we may want to move the iterations and the completion signal onto a separate API. [06:36] In fact, let's hand off that task to a separate agent."”
From snapshot/web/youtube.com/watch-v-dtaj2dod3ko.md, lines 95–96: “So, in this grilling session, we're down to question 13, actually, and we've got a sort of final uh resolution from the agent. [08:00] And then we can see I say, "Hand off to prototype the difficult bits here”
From snapshot/web/youtube.com/watch-v-dtaj2dod3ko.md, line 101: “Take all of the learnings from the prototype, anything that's not directly captured in the prototype itself or that's non-obvious, give me a handoff document that I can pass back to the planner."”
From snapshot/skills/handoff/SKILL.md, line 8: “Save to the temporary directory of the user's OS ($TMPDIR, else /tmp; %TEMP% on Windows) - not the current workspace.”
From snapshot/web/aihero.dev/skills-handoff.md, line 177: “Some environments clear temp between sessions (Codex is the reported case), and a reboot empties /private/tmp. If the next session isn't starting within the hour, or is starting under a different harness, copy the file somewhere durable yourself as soon as it's written.”
From snapshot/web/aihero.dev/skills-handoff.md, line 180: “Point at the file rather than pasting the summary into a shell command. The shell mangles a summary that contains backticks or $(...) when you interpolate it into claude "<summary>". The usual result is silent truncation rather than an error”
From snapshot/web/aihero.dev/skills-handoff.md, line 189: “The next agent trusts the document and does not re-check it, so a belief written as a fact becomes a false premise for everything that follows. Read the document before you hand it over, and downgrade anything you only assumed.”
From snapshot/skills/handoff/SKILL.md, line 10: “Include a "suggested skills" section in the document, naming which skills the next agent should call the Skill tool for.”
From snapshot/skills/handoff/SKILL.md, lines 12–14: “Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead. Redact any sensitive information, such as API keys, passwords, or personally identifiable information.”
From snapshot/skills/handoff/SKILL.md, line 16: “If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.”
