# handoff

> A Matt Pocock Claude Code skill that compacts the current conversation into a handoff document so a fresh agent can pick up the work — saves to a path produced by mktemp -t handoff-XXXXXX.md, suggests the skills the next session should reach for, and references prior artifacts (PRDs, plans, ADRs, issues, commits, diffs) by path rather than duplicating them.

**Use case**: Compact the conversation into a handoff doc for the next agent

**Canonical URL**: https://agentcookbooks.com/skills/handoff/

**Topics**: claude-code, skills, context-engineering

**Trigger phrases**: "handoff this conversation", "compact for the next agent", "write a handoff doc"

**Source**: [Matt Pocock](https://github.com/mattpocock/skills/tree/main/skills/productivity/handoff)

**License**: MIT

---

## What it does

`handoff` compacts the current conversation into a handoff document targeting a fresh agent or operator picking up the work later. The skill's frontmatter takes an `argument-hint` ("What will the next session be used for?") and tailors the doc accordingly.

The discipline of the skill is structural:

- **Output location.** Save to a path produced by `mktemp -t handoff-XXXXXX.md`, read before write.
- **Suggest the next-session skills.** Inline pointer to which skills the receiving agent should consider activating.
- **Reference, don't duplicate.** Prior artifacts (PRDs, plans, ADRs, issues, commits, diffs) get referenced by path or URL rather than re-embedded. The handoff doc is the *meta-state*, not a re-export of everything the session touched.

## When to use it

Reach for it when:

- A session has produced enough state to be worth resuming (a long debug, a partial refactor, an in-flight feature) and the context window is approaching compaction
- You're handing work to another operator, agent, or your own future self after a break
- A blocker has surfaced that needs to be resolved out-of-session and you want a clean resume point

When *not* to reach for it:

- The session ended cleanly with no outstanding state — a commit message is enough
- The state is entirely captured in artifacts already (issues, PRs, commits) — pointing the next session at those is the handoff

## Install

The skill is distributed via Pocock's [skills repo](https://github.com/mattpocock/skills). Install via his recommended path (`npx skills add` or manual copy into `.claude/skills/handoff/`) — see the repo README for canonical install instructions.

The skill accepts an `argument-hint`-style description on invocation, e.g. "handoff for the auth-migration follow-up" — this gets factored into the doc's framing.

## What a session looks like

A single-round-trip skill: you trigger it (optionally with an argument describing the next session's focus), the agent reads its own conversation, generates a `mktemp` path, writes the handoff doc, and surfaces the path. The next session starts by reading that doc.

The handoff doc itself follows a typical shape: what the session was for, what's done, what's open, the artifacts already produced (referenced by path), and the skills the receiving agent should consider activating first.

## Receipts

TODO — to be filled in from a real session. When the skill is triggered in production use, capture: length of the handoff doc vs the conversation it compacts, whether the receiving session was able to resume from the doc alone, and whether the "reference, don't duplicate" rule held up or whether some context still needed re-embedding for the next agent.

## Source and attribution

Originally written by [Matt Pocock](https://github.com/mattpocock). The canonical `SKILL.md` lives in the [`productivity/handoff` folder](https://github.com/mattpocock/skills/tree/main/skills/productivity/handoff) of his public skills repository.

License: MIT. You can install, adapt, and redistribute the skill, with attribution preserved.

This page documents the skill from a practitioner's perspective. For the formal spec and any updates, defer to the source repo.