Guide · Agent skill
How to use the Handoff Document Writer agent skill (handoff)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The handoff skill asks your AI agent to write a handoff document that summarises the current conversation, so a new agent session can continue the work without you re-explaining everything. It is useful when you hit context limits mid-task or need to pass long-running work to another agent or teammate. This guide explains what the skill does, how to install it, how to trigger it, and what to check before you rely on it.
Handoff Document Writermattpocock/skills · MIT Download the skill Quick start
- 1Download the skill. Download the handoff skill ZIP from this page. It contains agents/openai.yaml and SKILL.md.
- 2Unzip into a skills folder. For a personal install, unzip into ~/.claude/skills/. For one project, unzip into that project's .claude/skills/ folder.
- 3Or upload in the Claude apps. In the Claude apps, open Settings → Capabilities → Skills and upload the skill.
- 4Start a long session. Work on your task in an agent session as normal.
- 5Request the handoff. Ask the agent for a handoff document, and state what the next session will focus on.
- 6Check the saved file. Find the document in your OS temporary directory and review it for missed secrets.
- 7Start the new session. Open a fresh session and point the new agent at the handoff document.
What is an agent skill and what does handoff do?
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent can load when it needs them. The handoff skill is one of these: it tells the agent to compact the current conversation into a handoff document for another agent to pick up.
When it runs, the agent writes a document that summarises the conversation. Rather than copying existing work, the document points to artifacts such as specs, plans, ADRs, issues, commits and diffs by path or URL. It includes a "suggested skills" section naming which skills the next agent should call. It also redacts sensitive information such as API keys, passwords and personally identifiable information.
- Summarises the current conversation so a fresh agent can continue the work
- References specs, plans, issues and commits by path or URL instead of duplicating them
- Lists suggested skills for the next agent to use
- Redacts API keys, passwords and personal data where it recognises them
- Saves the file to the OS temporary directory, not your workspace
How do you install the handoff skill?
Download the ZIP for the handoff skill from this page. The skill is in the productivity folder of the mattpocock/skills repository and contains agents/openai.yaml and SKILL.md.
Install it in one of two ways. For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. Alternatively, in the Claude apps, open Settings → Capabilities → Skills and upload the skill there.
- Personal: unzip into ~/.claude/skills/
- Project only: unzip into your project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload
~/.claude/skills/handoff/How do you trigger the handoff skill?
The skill's metadata sets disable-model-invocation to true, so the agent does not start it on its own. You invoke it with a natural request near the end of a session, when you want to move the work somewhere else.
The skill also accepts an argument: a description of what the next session will be used for. If you pass one, the agent tailors the document to that focus. The argument hint in the skill reads: "What will the next session be used for?"
- Ask for a handoff document when you are close to a context limit
- Describe the next session's focus so the document is tailored to it
- Ask the agent to write the handoff before you close a long session
What are some example requests?
Keep requests specific about the next session's goal. The skill works from the conversation so far, so mention the focus you want the next agent to have.
- "Write a handoff document for the next session, which will finish the payment retry logic."
- "Compact this conversation into a handoff for a teammate who will review the migration plan."
- "Create a handoff document focused on the failing login tests, and suggest the skills the next agent should use."
What should you check before relying on the handoff?
The handoff document is saved to your system's temporary directory, which the source describes as $TMPDIR, falling back to /tmp, or %TEMP% on Windows. The OS may delete it, so copy anything you need to keep. The skill is not a substitute for permanent project documentation.
Redaction depends on the agent recognising sensitive data. If the conversation contains secrets in an unusual format, check the document before sharing it. The skill requires nothing beyond the agent itself, runs no scripts and uses no network, according to its listing.
- The file is saved to the temporary directory, not the project folder
- The OS may delete temporary files, so do not treat the handoff as permanent records
- Review the document for secrets the agent may have missed
- Redaction is only as reliable as the agent's recognition of sensitive data
Tips for a good handoff
Give the skill a clear purpose for the next session, because the document is tailored to it. Keep the real artifacts in version control or your issue tracker, since the handoff links to them rather than copying them. Ask the agent to reference specs, plans and commits by path so the next agent can open them directly.
- State the next session's goal as the argument
- Make sure specs, plans and commits exist before you hand off, so the references resolve
- Start the new session by pointing the next agent at the handoff file
What people use it for
- Continuing a feature in a new chat after hitting a context limit
- Handing a half-finished migration to a teammate or another agent
- Passing a debugging session to a fresh agent with the failing tests and commits referenced
- Giving a reviewer a summary of a plan, with links to the spec and issues
Frequently asked questions
How do I install the handoff agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for a personal install, or into your project's .claude/skills/ folder for one project. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
Is the handoff skill free to use?
The skill is published under the MIT licence in the mattpocock/skills repository. This page does not list any price, so check the repository for the licence terms.
What do I need to run the handoff skill?
The source lists no extra requirements. It does not run scripts and does not use the network, so it works through the agent using the skill's instructions.
Where does the handoff document get saved?
It is saved to the OS temporary directory: $TMPDIR if set, otherwise /tmp, or %TEMP% on Windows. It is not saved in your current workspace, and the OS may delete it, so do not use it as permanent project documentation.
Does the handoff skill remove API keys and personal data?
The skill instructs the agent to redact sensitive information such as API keys, passwords and personally identifiable information. Redaction depends on the agent recognising the data, so review the document before sharing it.
Can I use the handoff skill instead of writing project docs?
No. The file is temporary and is meant for passing work to another agent. Keep permanent documentation in your repository, issue tracker or docs folder.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
The handoff skill suits developers who run into context limits mid-task, or who need to pass long-running work to another agent or teammate, and who want the next session to reference existing specs, plans and commits. It is a poor fit for permanent documentation, or for conversations containing secrets that may slip past redaction. In those cases, write the record yourself or keep it in your repository.
Download the skill