Guide · Agent skill
How to use the Claude Handoff agent skill (claude-handoff)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The claude-handoff skill lets you pass your current Claude conversation to a fresh background agent, which starts working on the next task right away while your current session stays free. It is aimed at developers who use Claude Code and want to continue a long coding session in a clean context window. By the end of this guide you will know what the skill does, how to install it, how to trigger it, and what risks to check before using it.
Claude Handoffmattpocock/skills · MIT Download the skill Quick start
- 1Confirm Claude Code is installed. The handoff relies on the claude --bg background option and the claude agents command, so check that your Claude Code CLI supports them.
- 2Download the skill ZIP. Get the claude-handoff ZIP from this page. It contains agents/openai.yaml and SKILL.md.
- 3Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use or into .claude/skills/ in a project.
- 4Commit or stash your work. Because the background agent edits files in the same directory, secure any uncommitted changes first.
- 5Invoke the skill with a focus. Start the skill and describe what the next session should do, so the summary is tailored.
- 6Monitor the background agent. Run claude agents to see the job named with your --name value and manage it.
What the claude-handoff skill does
When invoked, the agent writes a summary of the current conversation, with redactions for secrets and personal data. It saves that summary to a temporary file in your operating system's temporary directory, then launches a separate background Claude Code agent seeded with the summary as its starting prompt.
The new agent runs in the same working directory and returns control to you immediately. The summary also includes a "suggested skills" section that names which other skills the next agent should use.
Install the claude-handoff skill
Download the ZIP for the skill from this page. The skill's files are agents/openai.yaml and SKILL.md. You can install it in one of two ways.
For Claude Code, unzip the download into your user skills folder ~/.claude/skills/, or into a project's .claude/skills/ folder if you want it only for one repository.
In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project
Trigger the skill with a natural request
The skill's frontmatter sets disable-model-invocation to true, so it is meant to be started deliberately rather than by the model on its own. The skill accepts an optional argument describing what the next session will be used for, and the summary is tailored to that focus.
Check the skill's trigger behaviour in your own setup before relying on it, since the source does not list specific phrases.
- Describe the next session in the argument, for example what feature or bug the next agent should work on.
- Leave the argument out to hand off the conversation without a specific focus.
Check the background agent with claude agents
The background agent is started with the claude --bg command and named with -n or --name, which sets the display name shown in the job list, session picker and terminal title. Use the claude agents command to see and manage it.
The underlying launch pattern in the skill is: claude --bg --name "<descriptive name>" -- "$(cat <summary file>)". Passing the file this way keeps the shell from running backticks or expanding $ inside the summary.
- Always give the agent a descriptive name, such as "Fix login bug".
- Use claude agents to monitor or manage the running agent.
claude --bg --name "Fix login bug" -- "$(cat <summary file>)"Safety notes: scripts, files and data
The skill runs scripts and the background agent edits files in the working directory. The skill does not use the network. Because the summary becomes the new agent's prompt and is saved to a temp file, any sensitive data that was not redacted stays in that file.
Do not use this skill in a repository with uncommitted work you do not want touched, and be cautious on sensitive projects where the summary might still contain data the redaction missed.
- Commit or stash uncommitted work before handing off.
- Review the summary file in the temp directory if the project contains sensitive data.
- Remember the background agent works in the same directory as you.
Tips for a clean handoff
Give a specific argument so the summary focuses on the right task. The skill tells the next agent to reference existing specs, plans, issues, commits and diffs by path or URL rather than repeating them, which keeps the summary short.
Name every background agent so you can tell them apart in the job list.
- Reference existing artifacts by path or URL instead of copying them into the summary.
- Use distinct names for parallel agents.
- Monitor progress with claude agents.
What people use it for
- Continuing a long coding session in a clean context window after the old one has grown large.
- Starting a follow-up bug fix in the background while you keep working in your current session.
- Passing a feature task to a fresh agent with a summary that points to existing specs or issues by path.
Frequently asked questions
How do I install the claude-handoff skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ inside a project. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
What do I need to run claude-handoff?
You need the Claude Code CLI with the --bg background agent option and the claude agents command, plus a shell that can write to the OS temporary directory. The skill runs scripts, but the source says it does not use the network.
Is the claude-handoff skill free?
The skill is published under the MIT licence, as stated on this page. The source does not give pricing for Claude Code itself, so check Anthropic's terms for that.
Where does the handoff summary get saved?
The skill saves the summary to the temporary directory of your operating system, then passes it to the new agent as its starting prompt. Because the file persists there, review it if the project is sensitive.
Does the background agent change my files?
Yes. The background agent runs in the same working directory and can edit files, so avoid using the skill in a repo with uncommitted work you want to keep untouched.
How do I check or stop the background agent?
Use the claude agents command to see the running agent, which appears under the name you gave with -n or --name.
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
Use claude-handoff if you already work in Claude Code, want to continue long sessions in a fresh context, and can keep your working directory clean before handing off. Pick something else if you have not installed Claude Code, work in a repo with uncommitted changes you need to protect, or handle data too sensitive to risk a missed redaction in a temp file.
Download the skill