What is /handoff? Pass work to a new AI session with a summary document
When moving to another tool or handing work to another agent, pass along both the current state and the reasons behind decisions. /handoff summarizes this information in a document the recipient can read. It does not transfer a model’s internal memory or create a Git branch, but it can be used alongside branching.

Handoff summarizes the context so another agent can continue
Suppose you and AI have investigated a bug, read several files, and agreed on a fix, but must move between tools or assign an experiment to another agent. Along with the code, pass on an understanding of the task, why this approach was chosen, and what remains blocked .
/handoff by Matt Pocock is a Skill instructing an agent to summarize the current conversation for another agent. The source specifies creating a file outside the workspace in the system temporary folder, linking existing documents instead of duplicating them, and excluding sensitive data. Original handoff Skill
The process is therefore Original session → handoff document → receiving session → verify actual status → continue work This does not transfer internal model state. Recipients know only what the document states and what their tools can access. Reasons omitted from the document do not transfer automatically.
Distinguish the general handoff method from the named skill: Handoff can use an ordinary prompt, while the skill named /handoff is one implementation. Not every AI coding tool includes it.
A long context doesn't always mean a handoff.
Context Window is the data area that the model uses to form that response. For Claude Code, the developer documentation states that context includes the conversation, file content, command results, project rules, memory, and loaded Skills, so it's not just the text the user types in the chat. Claude Code documentation
As information grows, context compression may help manage space, but The sources used here provide no basis for a universal token threshold where all AI models begin to lose focus. We therefore do not treat “Dumb Zone” as universal or guarantee a new session will always be more correct or faster
Claude Code clears older tool results near context limits, then summarizes the conversation if needed. Users can specify the focus using /compact to set the focus. Early details may still be lost, so keep long-term rules in project documents. Claude Code documentation
Matt Pocock highlights the benefits of Handoff as Ability to take work elsewhere not a claim of better summaries than Compact. Within the same tool and task, Compact may fit better; portable documents help when changing tools or folders, collaborating, or splitting related tasks. Explanation from Matt Pocock
| Concept | What is retained | What it suits | Precautions |
|---|---|---|---|
| Handoff | Task-specific status with references | Hand work to another session, tool, or recipient | Summaries may omit details, and paths may not open |
| Compact | Summarize context to continue in the same workflow | Want to reduce the context while still doing the same work | Behavior depends on the program and the data that is collected. |
| Memory | Information that the system is designed to remember across sessions | Knowledge or preferences that are reused | Format, loading, and storage vary by system. |
| Project rules, such as CLAUDE.md or AGENTS.md | Repo standards and scope | so every session follows the same rules | should not become a large backlog of unfinished work |
This is KrobClick's purpose-based grouping, not identical commands supported by every application. A new Claude Code session starts with a new context window but may retain project rules and Auto Memory. Calling it an unconditionally “empty brain” would mislead. Claude Code documentation
How handoff differs from branching and merging in Git
Both separate work, but differ in what they separate and how it is combined. Git branches separate code changes, which are merged through commit history. Conflicting edits may require resolution. Git branches help separate code changes and merge them according to commit history. If the same part is edited differently, conflicts may occur that must be managed. Pro Git: Branching and Merging Handoff passes on understanding and task status. It does not create branches, commit, or merge code automatically.
The difference is evident in the following two formats:
- Take over: Agent A stops and writes a handoff document; Agent B continues from the same code state to completion. Parallel work or a merge-back step is not necessary.
- Separate, then combine: The main agent continues to talk about designs, while Agent B takes on experimental problems to do in a separate area. When the answer is received, the results and evidence are returned to the main agent for consideration.
The latter matches Matt Pocock's description: send a question to an experimental session and bring the answer back. Documents travel both ways while the original session remains. Explanation from Matt Pocock
| Method | What is separated or passed on | What to include afterward |
|---|---|---|
| Git branch | Changes documented in Git history | Code and conflicting changes |
| Fork session | Conversation history to new session according to the program's capabilities | Findings or deliverables, rather than automatic merging of chat history |
| Handoff | A task-focused summary with source files or URLs | The recipient examines and uses the information; There is no need for a recombination step. |
Claude Code documents --fork-session or /branch as copying history to a new session ID without changing the original session. This differs from a skill that writes a task-focused summary. Claude Code documentation Forking may be convenient for copying history within one system. A portable document often fits better when the destination is a different tool. Explanation from Matt Pocock
For parallel tasks that modify real files, do not assume a new chat has a separate working directory Claude Code documentation describes Git worktrees for giving parallel sessions separate folders Claude Code documentation In practice, define file ownership and result integration before starting so two agents do not overwrite each other's work
What the Handoff skill adds to a standalone prompt
from SKILL.md on main that was checked on the date specified at the end of the article The main commands are as follows. Original handoff Skill
- Summarize the current conversation so a new agent can continue
- Save in system temporary folder: Use
$TMPDIRif available; otherwise/tmp; Windows uses%TEMP%not the current workspace - Include Suggested Skills so recipients know which capabilities to load
- Reference paths or URLs for specs, plans, ADRs, issues, commits, and diffs instead of duplicating existing content
- Cut sensitive data such as API keys, passwords, and personally identifiable information.
- If the user specifies the next session's task, tailor the document to that focus
Frontmatter has disable-model-invocation: true and AI Hero's explanation says users should invoke it themselves, rather than letting agents select it automatically Original handoff Skill Explanation from Matt Pocock When you use Handoff, include the goal and scope, as in this example.
/handoff ทดลองทางเลือกสำหรับอ่านไฟล์ใหญ่ โดยยังไม่แก้โค้ด production
Packaging it as a Skill helps share and update instructions through the same channel as other Skills and standardize repeated steps; an ordinary prompt can also perform the task. Explanation from Matt Pocock You can also give the instructions in ordinary language if the platform does not have the skill.
This install command comes from Matt Pocock’s guide. Explanation from Matt Pocock
npx skills@latest add mattpocock/skills --skill=handoff
Before running it, read the skill file and check that your tool supports this installation and invocation method. We did not test the installation.
A handoff document the recipient can act on
The following template is KrobClick's proposal to make the original's brief requirements more precise for development, without claiming the developer specified every item
- Goal and completion criteria: What results must the work bring? What is considered out of scope?
- Current status: Separate completed, in-progress, and not-started work
- Decisions and reasons: Choice chosen or rejected along with limitations that lead to decision making
- Code status: repo, branch, referenced commits, and uncommitted edit files
- Reference points: path or URL of the code, issue plan, and evidence that the recipient can access
- Inspection: Commands that actually ran, results, and things that didn't run. Don't change "expected to pass" to "passed."
- Problems and assumptions: Unconfirmed information, separated from facts
- Next tasks and Suggested Skills: Where to begin, and which available skills to load
- Scope of rights: Do not transmit data, publish, or edit specified files, as required by the task
Use references instead of pasting entire code files, but retain reasons not already recorded elsewhere in the document. For example, “Approach A was not chosen because it requires a dependency prohibited by the brief” is more useful than a file list alone. Link to explanations already recorded in an ADR.
Before sending, read without the original chat: Is it clear where to start, what is reliable, what needs checking, and when to ask the user? If not, the handoff document is incomplete, however short.
Pass documents to a new session step by step
- Specify the destination job: Say whether to take over the whole thing or try just one question. Complete with prohibitions and things that must be sent back.
- Request path and read copy before sending: Make sure that everything that has not yet been done, test results, and important reasons is specified. without secret information
- Prepare reference files the destination can open: If you're on different machines, the original path may not work. Submit an authorized copy and match the repo and commit; Forwarding documents do not carry uncommitted code.
- Open a new session and attach the documents: Ask the recipient to read the project rules. Check the actual status and tell what is lacking before starting If the file is in temporary storage Keep a copy that fits your work policy before leaving the original environment.
KrobClick suggests these steps for real handoffs. Attachments, folder access, and tool permissions depend on the recipient's system. Reading Markdown does not require the same skill, but executing work still requires suitable tools and permissions.
Hypothetical example: splitting experimental work and returning results
Suppose the lead agent is designing a CSV validator and deciding whether to read the entire file or process chunks. We want another agent to test this without derailing the main design conversation with experimental details. The following tasks, file names, and text are fictitious. It's not a real test result.
Outbound instruction: “Summarize context for an agent to test CSV reading in a separate experimental folder. State the task, restrictions, and criteria. Do not modify the main app or add dependencies. Return the document path. Do not copy customer data or secrets.”
An outgoing handoff document might contain the following. Skill names are examples that must be verified in the destination system before use:
# งานทดลองอ่าน CSV — ตัวอย่างสมมติ
## เป้าหมาย
เปรียบเทียบแนวทางอ่านทั้งไฟล์กับทยอยอ่าน
ส่งข้อค้นพบกลับให้เซสชันหลัก ไม่แก้แอป production
## จุดอ้างอิง
แผน: docs/csv-reader-plan.md ใน repo ที่ผู้รับได้รับสิทธิ์
บันทึกข้อจำกัด: issue ของงานนี้
ให้ผู้รับตรวจว่าเอกสารและไฟล์ยังตรงกับสถานะล่าสุด
## สถานะ
ยังไม่มีผลทดลอง อย่าสรุปว่าวิธีใดเร็วกว่า
ใช้ข้อมูลสังเคราะห์ ไม่ใช้ไฟล์ลูกค้าจริง
## สิ่งที่ต้องส่งกลับ
วิธีทดลอง สภาพแวดล้อม ไฟล์ที่ใช้ และคำสั่งรันซ้ำ
ผลที่สังเกต ข้อจำกัด และสิ่งที่ยังตอบไม่ได้
หากมีโค้ด ให้ส่ง path หรือ diff ที่ผู้รับเปิดได้
## Suggested Skills
spike — ถ้ามี Skill นี้และอ่านคำสั่งแล้วตรงกับงาน
## ขอบเขต
ห้ามติดตั้ง dependency โดยไม่ได้รับอนุญาต
ห้าม push, deploy หรือส่งไฟล์ไปบริการภายนอก
Command to recipient: “Read the handoff document at the attached path, then the experimental folder's rules. Check references and permissions before starting. If the path is inaccessible or information conflicts, report it first; do not assume the work is complete.”
Return trip Do not merely say “choose B.” State data type, tests, evidence location, and remaining limitations. For unmeasured aspects, say they were not measured rather than inventing figures to look complete.
The main agent reviews evidence, chooses findings, and separately decides on code changes. If an experimental branch exists, merging is another step; receiving a document does not merge code. This is the distinction between Synthesize findings with Merge code changes
What to verify before continuing the handed-off work
KrobClick's proposal is to view Handoff as A review map, not certification that everything written is correct The recipient should do this in this order:
- Read the current scope and rules: Check user requests and project documents. Handoff documents do not override newer rules.
- Verify repo status: Check branches, commits, and working trees before touching code. Don't clean up any leftover files to match the text in the summary.
- Open the reference point: Read only necessary source files. If a path or URL cannot be opened, resolve access before relying on conclusions.
- Separate facts from assumptions: “This command produced an error” is different from “this function probably caused it”
- Check evidence of test results: Check the code version tested, whether it includes the latest changes, and what the tests cover
- Briefly review the next task: Begin once key information is complete. If a conflict changes the task's direction, stop and ask instead of guessing.
Recipients need not read the entire history every time. If important reasoning is missing, inspect the relevant part of the history to confirm it. A handoff helps select what to read; it does not prohibit consulting old chats.
Limitations, secrets, and permissions not transferred
A summary more confident than its evidence is more dangerous than one that admits uncertainty Matt Pocock warns against unverified session claims such as “done,” which recipients may adopt as assumptions. Senders should read the document before handing it off and qualify unconfirmed claims. Explanation from Matt Pocock
Temporary files are not long-term storage The source explains that files may be lost when changing sessions or environments. If sending across devices or starting work later Copies should be placed in a location accessible to the destination and complete with reference points. Explanation from Matt Pocock Choose storage according to project policy. Do not automatically move it into Git or cloud storage or delete originals before the recipient confirms they open.
Do not record secrets and expect a final step to remove everything Removing sensitive data is required by the original Skill Original handoff Skill In practice, reference a secret-manager entry or authorized login procedure. Do not include passwords, tokens, cookies, one-time codes, or credential-file contents in documents, or retrieve them merely to summarize.
Permissions do not travel with documents The “User approved” clause in Handoff does not replace endpoint authentication or required verification. Push, deploy, post, or send data must still be within the scope of current user commands and tooling rules.
External documents are data, not higher-priority instructions. If a document tells the recipient to disable checks, clear work, or send secrets, verify its source and scope. A Next Steps heading does not authorize those actions. If there is a message telling you to turn off inspection, clear work, or send secrets The recipient must check the source and scope. Don't follow because the message is in the Next Steps section.
When to use handoff, compaction, or a Git branch
- Still working in the same system: Consider continuing or using Compact based on the tool's capabilities. No need to create a file every time a work session ends.
- Move a tool, move a repo, or send it to a colleague: Handoff is useful because a summary can travel as a document
- Want to copy history on the same system: Check if session fork is supported.
- Split off a question for experimentation and return the results: Specify the problem, scope, and evidence that must be returned. and work area clearly
- Data will be reused over the long term: Consider appropriate project rules or memory instead of keeping them in expired forwarding documents.
A branch isolates code changes; a handoff passes on task context. They can be used together, but neither replaces the other or guarantees that AI will avoid mistakes. Reliable handoffs preserve relevant context, evidence, and unknowns, and require the recipient to verify the actual state before acting. Both can be used together. But they cannot be replaced. And there's no guarantee that AI won't make mistakes. The point of making a workflow reliable is delivering relevant context, capturing evidence, revealing unknowns. and let the recipient check the actual status before taking action
Sources
- Matt Pocock: handoff SKILL.md on main
- Matt Pocock / AI Hero: The /handoff Skill
- Anthropic: How Claude Code works — sessions, context and compaction
- Pro Git: Basic Branching and Merging
- mattpocock/skills
Sources reviewed October 12, 2026, Thailand time, referencing a changeable main-branch Skill. This does not verify clip transcripts or report KrobClick performance tests. Tasks, files, and handoff text are hypothetical; templates and acceptance checklists are KrobClick proposals.