Capture the working state of a conversation in a temporary Markdown document for a fresh agent to continue a defined task.
Install and prepare
Run the following in your project terminal, then use the prompt below in Claude Code. This installs editable, project-scoped skill files.
npx skills@latest add mattpocock/skills --skill handoff --agent claude-code
For Codex, replace claude-code with codex in the command and /handoff with $handoff in the prompt. With the complete Claude Code plugin, select /mattpocock-skills:handoff instead; avoid installing the same skills twice.
Invoke it while the original working context is available and explain the next agent’s objective. The file goes to the operating system’s temporary directory; move it separately if it needs long-term retention.
Your first task
Adapt the scenario and paths to your project, then enter this in the agent conversation:
/handoff
The next session will review payment retry behavior. Capture confirmed causes, changed files and remaining failing tests. Link existing specs and commits rather than copying all the code.
Work through the task
Select context for the next task
A handoff is not a compressed transcript. Reviewing payment retries needs triggers, ruled-out causes, relevant files and failing checks; earlier color discussions probably do not matter. A specific next objective reduces the amount of investigation the receiving agent must repeat.
Link existing artifacts
Reference existing specs, plans, ADRs, issues and commits by path or URL. Add working state those artifacts do not already express, such as an unfinished experiment. This avoids producing a second full specification that can drift away from the original.
Give the document to the next session
Take the absolute path and ask the fresh agent to read it before continuing the task. When moving across machines or directories, check that referenced artifacts are accessible. The document itself does not transfer code, install dependencies or grant account access.
Check the result
Read the document and confirm that the goal, state, references and suggested skills are understandable and sensitive details are removed. Ask the receiving agent to summarize its next step to reveal any missing context early.
Common questions
Does it open the next session? It creates the document; opening another session is a separate action.
Why is it outside the project? The default temporary location keeps transient handoff material out of the repository.
Do I need it to continue in the same session? Usually not when no work needs to travel.
Check whether the work really needs to move
If you are continuing the same task in the same tool and directory, compaction is usually enough. Handoff is for changing tools or directories, transferring work to a colleague, or giving a side investigation to another agent. In the side-task case, state what the main session is still doing and exactly what the fork owns, so both do not edit the same target. The Skill writes a portable file; it does not create the new session or copy the repository and account permissions.
Open the result as if you were a stranger. Can you state the next objective in a sentence or two? Are specs, issues, diffs, and experiments linked by accessible paths rather than copied wholesale? Does it name failed checks, the current branch, and boundaries the next agent must respect? Remove keys and short-lived credentials. Ask the new session to read the file and repeat its first step. If it still has to ask you for the original context, the handoff is missing important state.
Hand off one side investigation
Suppose the main session is implementing account migration and a fresh session should audit accessibility only. Ask: “Use handoff to record the current branch, changed screens, runnable checks, and unresolved issues. The next session should assess keyboard and screen-reader behavior without changing migration logic. Link the existing issue and diff instead of copying the whole conversation.” Pass the temporary file path to the recipient and confirm they can access the same repository.
If the new agent cannot identify the first screen or protected files, the boundary is missing. If the document reads like a transcript, remove irrelevant background. Never include temporary tokens or private accounts. As the main task proceeds, avoid both sessions editing one screen simultaneously; split the files or actions again when scopes overlap.
Pass the summary without losing details
If you pass the handoff summary to a newly launched CLI session, avoid interpolating long text containing backticks, $(...), or quotes directly into a shell command. A claude-handoff user saw the command start successfully while a file path vanished from the text delivered to the new session. Write the summary to a file, pass it through a safe file-based or carefully checked mechanism, then ask the receiving session to restate the goal, changed files, unresolved questions, and next step. Open a plain /handoff file before ending the original session too.