Guide · Agent skill

How to use the Session Handoff Writer agent skill (handoff)

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The Session Handoff Writer is an agent skill (named handoff) that makes Claude write a structured HANDOFF.md file in your project folder. The file summarises the goal, what works and what is broken, which files matter, which approaches failed and why, and the next steps. This guide explains what the skill does, how to install it, how to trigger it, and what to watch for, so you can start a clean session without losing track of the work.

Session Handoff Writerthedotmack/claude-mem · Apache-2.0 Download the skill

Quick start

1Download and unzip. Download the ZIP from this page and unzip it so that SKILL.md sits in a folder named handoff.
2Place the skill folder. Move the handoff folder into ~/.claude/skills/ for all projects, or into the project's .claude/skills/ for one project.
3Start or open a session. Open Claude Code in the project where the work is happening, or upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
4Ask for a handoff. When the session is long, looping, or you need to stop, say something like "write a handoff doc" so the skill runs.
5Review HANDOFF.md. Check the goal, failed attempts, and next steps in the generated HANDOFF.md, and remove any secrets or sensitive details.
6Resume in a new session. Run /clear or start a new session, then say: Read HANDOFF.md and continue from where we left off.

What an agent skill is and what this one does

An agent skill is a folder with a SKILL.md file that tells Claude how to perform a specific task. Claude loads the instructions when a request matches the skill's description.

When triggered, the handoff skill has Claude review the whole session and write HANDOFF.md to the current working directory (the project root). The document is written for a fresh Claude that has never seen the conversation.

Goal: the end state the user is trying to reach
Current state: what is working, what is broken, and the exact symptom or error message
Files in play: relevant files with a one-line note on why each matters
What has been tried and why it failed
Current best theory and ordered next steps
Key constraints and user preferences
Memory pointers, if claude-mem is available

Install the handoff skill

Download the ZIP file from this page and unzip it. The package contains SKILL.md. Then choose one of the following locations.

For all of your projects, unzip the skill into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

Personal install: ~/.claude/skills/handoff/ (available in every project)
Project install: .claude/skills/handoff/ inside the project folder (available only there)
Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Trigger the skill with a natural request

You do not need a special command. The skill's description covers three situations: the session is getting long, Claude keeps retrying the same broken solution, or you want to stop and resume later. The skill also responds to phrases such as "handoff", "generate a handoff", "I want to start fresh", or "write a handoff doc".

Using the skill also works after /compact if Claude still lacks clear direction.

"Write a handoff so I can continue this in a new session."
"Claude keeps retrying the same fix. Generate a handoff doc."
"I want to start fresh. Write a handoff."
"I'm stepping away. Handoff please, so I can resume tomorrow."

Start the fresh session with the handoff

After Claude writes HANDOFF.md, it will tell you the file is ready. Run /clear or start a new Claude Code session. Then give the new session this instruction exactly as written in the skill, so it reads the briefing before doing anything else.

Open the new session and say: "Read HANDOFF.md and continue from where we left off."
If claude-mem is installed, the new session also gets the recent timeline automatically. HANDOFF.md adds the precise briefing on top of it.
Treat HANDOFF.md as a scratch file. Do not commit it. Delete it once the new session has picked up the work, or add it to .gitignore.

Read HANDOFF.md and continue from where we left off.

The skill runs no scripts and uses no network access, according to the package details. It does, however, write a file that captures error messages and file paths verbatim. That content may include secrets or sensitive details.

Because of this, do not commit HANDOFF.md to version control, and review it before sharing it with anyone.

Runs scripts: no
Uses network: no
Requires Claude Code or a compatible agent that can read and write files in the project folder
The memory section needs the claude-mem plugin; it is skipped if its tools are unavailable

Tips for a useful handoff

The quality of the handoff depends on what the session contains. The skill asks Claude to be specific: exact file paths, function names, error text, and the approaches that failed. Vague next steps give the new session little to work with.

Use the handoff when it adds value. For a short, simple task, a handoff document usually adds little.

Ask for the handoff while the failure details are still in the session.
Check that the "What Has Been Tried" section lists the failed approaches and the reasons they failed.
Check that the Next Steps begin with a concrete action the new session can start immediately.
Edit HANDOFF.md by hand if something important is missing before you start the new session.

What people use it for

Handing a stuck debugging task to a fresh session after Claude keeps retrying the same fix
Pausing a multi-file refactor at the end of the day and resuming the next morning with exact next steps
Passing an in-progress task to a colleague's Claude session, with the failed attempts recorded so they are not repeated
Clearing a cluttered session after /compact still leaves Claude without clear direction

Frequently asked questions

Is the handoff skill free to use?

The source material for this skill is licensed under Apache-2.0, which is the licence listed for this item. Check the licence file in the source repository for the full terms before redistributing it.

What do I need to run the handoff skill?

You need Claude Code or a compatible agent that can read and write files in your project folder. The claude-mem plugin is optional; without it, the memory pointer section is skipped.

How do I install the handoff skill in Claude Code?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into .claude/skills/ inside one project. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.

Does the handoff skill need network access or run scripts?

No. The package details state that it runs no scripts and uses no network access. It writes a HANDOFF.md file in your project folder.

Will the new session remember my earlier conversation without a handoff?

Not automatically unless claude-mem is installed. With claude-mem, the new session gets recent observations automatically, and the handoff adds the goal, failed attempts, and next steps on top of that.

Should I commit HANDOFF.md to git?

No. The file captures error messages and file paths verbatim and may contain sensitive details. Delete it after the new session picks up the work, or add it to .gitignore.

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 this skill if you run long Claude Code sessions that have become repetitive or confused, or if you need to stop mid-task and resume with clear context. Skip it for short, simple tasks, or if you expect automatic recall of earlier sessions without claude-mem installed.

Download the skill