handoff

Trigger phrases

Phrases that activate this skill when typed to Claude Code:

• handoff this conversation
• compact for the next agent
• write a handoff doc

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. 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. The canonical SKILL.md lives in the productivity/handoff folder 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.