{"slug": "the-handoff-skill", "title": "The /Handoff Skill", "summary": "Matt Pocock's /handoff skill for coding agents compacts a conversation into a markdown file written to the OS temporary directory, enabling portability across harnesses, directories, or colleagues. The skill is triggered by typing /handoff and is intended for four situations, including swapping harnesses and branching parallel work, while /compact remains the default for same-session resumption. Secrets are redacted, and specs, plans, and diffs are referenced by path or URL rather than copied.", "body_md": "# The /handoff Skill\n\nWrite up a long session so another agent can continue it.\n\nInstall this skill\n\n`npx skills@latest add mattpocock/skills --skill=handoff`\n\nThen type `/handoff`\n\nin your coding agent.\n\n- Source\n[mattpocock/skills](https://github.com/mattpocock/skills)\n\n## On this page\n\n[What it does](#what-it-does)\n\n`handoff`\n\ncompacts the conversation you are in into a **handoff document** — one markdown file, written to your OS's temporary directory rather than into the workspace, that a fresh [agent](/ai-coding-dictionary/agent) can read to pick the work up.\n\nWhat it buys is **portability**, not compression. That makes the skill narrower than it sounds. You need a file only when the work has to *travel* — to a new [harness](/ai-coding-dictionary/harness), a new directory, a colleague, or a side task you want to fork off. If nothing is travelling, you do not need a handoff: staying in the [session](/ai-coding-dictionary/session), `/clear`\n\n, a [subagent](/ai-coding-dictionary/subagent) and `/compact`\n\ncover the ordinary end-of-phase case, and `/compact`\n\ncovers it more often than this skill does.\n\n[When to reach for it](#when-to-reach-for-it)\n\nYou invoke this by typing `/handoff`\n\n— the agent won't reach for it on its own. Pass a note about what the next session is for, and the document is written for it.\n\nFour situations are the whole trigger:\n\n| Situation | Why a file |\n|---|---|\n| Swapping harness — Claude → Codex | The new harness cannot see the old\n|\n\nFor anything else — same harness, same directory, you are done [grilling](/ai-coding-dictionary/grilling) and moving to implementation — `/compact`\n\nis the move. [ask-matt](/skills-ask-matt) carries the ordered tree over all five options at a phase boundary.\n\n[Branching is the use people skip](#branching-is-the-use-people-skip)\n\nThe skill's description reads like session resumption: write a summary, end here, resume there. Read that way it looks like a worse `/compact`\n\n, so it gets skimmed past. 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.\n\nThat is what the detour through [prototype](/skills-prototype) uses. You are deep in a design conversation, you hit a question that only running code will settle, and you do not want to spend the thread you built on finding out. Hand off to a prototype session, get the answer, hand the answer back, and reference it from the original thread. Two crossings, one live conversation, nothing re-explained.\n\nThree of the five options at a phase boundary preserve different things: `/compact`\n\npreserves your intent, `/clear`\n\npreserves nothing, `/handoff`\n\npreserves the work's ability to move.\n\n[What travels, and what doesn't](#what-travels-and-what-doesnt)\n\nThe document carries the live thread — what's in flight, why, and what's next — plus a **suggested skills** section naming what the next agent should reach for. Secrets are redacted before it's written.\n\nWhat it deliberately does not carry is anything already written down. Specs, plans, ADRs, issues, commits and diffs are referenced by path or URL, never copied. That keeps the file small, and it keeps the settled detail in one place instead of two that drift.\n\n[Common questions](#common-questions)\n\n**Handoff or compact?**\n`/compact`\n\nunless something is travelling. Staying on the same task is a compact, not a handoff — same harness, same directory, and you need to stay in the loop is where the phase-boundary tree lands most days. `/handoff`\n\n's advantage is not that it summarises better; it's that the result is a file you can carry somewhere `/compact`\n\ncan't reach.\n\n**So what's the actual difference between compact, clear and handoff?**\nThree different things being preserved. `/compact`\n\ncompresses this context and keeps you going in a fresh window — intent survives. `/clear`\n\nempties the window and starts from nothing — correct when everything behind you is disposable, and one-way if it isn't. `/handoff`\n\nwrites a portable file — the work survives the move to somewhere else. Note that all three turn a ** primary source** (the conversation as it happened) into a\n\n**(a summary of it). Continuing is the only move that doesn't, which is why it's the first one to rule out.**\n\n[secondary source](/ai-coding-dictionary/secondary-source)**Where did my handoff file go?**\nThe temp directory, which is the most-reported friction with the skill: the paths are long, they differ per OS, and on Windows agents sometimes take several attempts to find the right one. Ask for the path back and keep it before you move on. Temp is deliberate: a handoff is a transit document, not an artifact you maintain. It is not a durable one either — see the next question.\n\n**My handoff vanished between sessions.**\nSome environments clear temp between sessions — Codex is the reported case — and `/private/tmp`\n\ngoes on reboot. 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. The same applies to anything the document *points at*: a dispatch that references other files in temp is a dispatch the next agent can't follow.\n\n**How do I actually hand it to the next agent?**\nOpen the fresh session and point it at the path: read this file, then continue. Point at the file rather than pasting the summary into a shell command — a summary containing backticks or `$(...)`\n\ngets mangled when it's interpolated into `claude \"<summary>\"`\n\n, and the usual failure is silent truncation rather than an error, so the new agent starts with a quietly incomplete brief.\n\n**Is this the same as /branch, --fork-session, or the built-in /handoff?**\nAnalogous, not identical, and\n\n`/branch`\n\nisn't a shipped skill here — `/handoff`\n\nis the canonical name. A fork inherits an exact copy of the context; this skill produces a *targeted*compression aimed at a stated next task, in a file. Where a fork will do — same machine, same harness, same directory — a fork is less work. The file wins the moment the destination is somewhere the fork can't go.\n\n**When does something belong in CLAUDE.md instead?**\nAsk whether it's true next month.\n\n`CLAUDE.md`\n\nis standing context about the project, loaded into every session whether it's relevant or not. A handoff is about one piece of work in flight and is dead once that work lands. Facts that keep getting re-explained are a `CLAUDE.md`\n\nproblem; a half-finished task is a handoff.**It captures the what, not the why.**\nA fair and repeated criticism. Two things help. Pass the argument — tell it what the next session is for — so the reasoning that bears on *that* is kept rather than flattened. And watch for confident claims the session never actually verified: \"X isn't built\", \"Y is done\". The next agent treats the document as a contract and will 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.\n\n**Why is it a skill rather than a slash command?**\nBoth work; they suit different situations. As a skill it ships and updates through the same install path as everything else here, which is what makes it shareable — the constraint that the agent won't fire it itself is set by its frontmatter rather than by the mechanism.\n\n[It's working if](#its-working-if)\n\n- The document is a small fraction of the conversation, and the specs, issues and diffs appear in it as paths and URLs rather than as copied text.\n- You can read it cold, without the original session open, and know what to do next.\n- The fresh agent starts working instead of asking you to re-explain the setup.\n- In the fork case, your original session is still sitting there untouched when you come back to it.\n- The suggested-skills section names the skill you'd have reached for yourself.\n- Nothing in it is a key, a token, or a password.\n\n[Where it fits](#where-it-fits)\n\n`handoff`\n\nis a **reach-for-it-anytime standalone** that lives at the seam between sessions rather than inside a build chain — but a narrow one, and the honest map is that you'll use it less often than the other four options at a phase boundary. Its closest neighbour is [prototype](/skills-prototype), because a prototype lives in its own directory and the round trip out and back is exactly the crossing this skill is for. When you're at a boundary and unsure whether to continue, clear, hand off, delegate or compact, [ask-matt](/skills-ask-matt) carries the tree that orders those five — and routes you over the rest of the set.\n\nSkill actions\n\n`npx skills@latest add mattpocock/skills`\n\nInstalls the whole set. Then type `/handoff`\n\nin your coding agent.\n\n[Skills.sh](https://www.skills.sh/mattpocock/skills)", "url": "https://wpnews.pro/news/the-handoff-skill", "canonical_source": "https://www.aihero.dev/skills-handoff", "published_at": "2026-08-15 20:45:49+00:00", "updated_at": "2026-08-15 21:10:52.169529+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents"], "entities": ["Matt Pocock", "mattpocock/skills", "/handoff", "/compact", "/clear", "Claude", "Codex"], "alternates": {"html": "https://wpnews.pro/news/the-handoff-skill", "markdown": "https://wpnews.pro/news/the-handoff-skill.md", "text": "https://wpnews.pro/news/the-handoff-skill.txt", "jsonld": "https://wpnews.pro/news/the-handoff-skill.jsonld"}}