mp-handoff

---
name: mp-handoff
description: Use when compacting the current Claude Code conversation into a handoff document a fresh agent can pick up — writes to `mktemp -t handoff-XXXXXX.md`, references existing artefacts instead of duplicating them.
source: https://github.com/mattpocock/skills/blob/main/skills/productivity/handoff/SKILL.md
generated: 2026-05-12T18:05:07.120Z
category: concept
audience: engineers
---

## When to use

- Wrapping a long session before context gets compacted out and you want the next agent to start clean
- Switching machines or sessions mid-task — the handoff doc carries the why, what's done, what's next
- Briefing a teammate's agent on a feature you've been driving
- Capturing what skills the next session should run (to-issues, tdd, diagnose, etc.)

## Key concepts

### compact, don't duplicate

Don't restate content already captured in PRDs, plans, ADRs, issues, commits, or diffs — REFERENCE them by path or URL. The handoff is the summary that ties existing artefacts together, not a copy of them.

### mktemp output path

Save the doc to a path produced by `mktemp -t handoff-XXXXXX.md`. Unique filename per session, no clobbering previous handoffs. READ the file before you write to it — mktemp creates an empty file, but reading it confirms the path is real.

### suggest next-session skills

End the handoff by suggesting which skills the next session should load (e.g. 'next session should run /tdd against the deepened module', '/triage to publish the bug'). Without this the next agent has to re-derive the plan.

### argument-hint

Frontmatter has `argument-hint: "What will the next session be used for?"` so when the user invokes /handoff the slash UI prompts them for a focus. If the user passes args, treat them as a description of what the next session will focus on and tailor the doc accordingly.

## API reference

```
Output path pattern
```

Use mktemp so each handoff lands in /tmp with a unique name. Read before write so the path is verified.

```
mktemp -t handoff-XXXXXX.md   # e.g. /tmp/handoff-AbC123.md
```

```
Skill body (verbatim)
```

Four short lines — the entire skill.

```
Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save it to a path produced by `mktemp -t handoff-XXXXXX.md` (read the file before you write to it).

Suggest the skills to be used, if any, by the next session.

Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.

If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.
```

## Gotchas

- Reference existing artefacts (PRDs, plans, issues, diffs) — don't duplicate them in the handoff body.
- Use `mktemp -t handoff-XXXXXX.md` for the output path so handoffs don't clobber each other in /tmp.
- Read the mktemp'd file first to confirm the path exists before writing to it.
- Always end with a 'suggested skills' section so the next agent isn't guessing what to load.
- If the user passes an argument (via /handoff <description>), use it to scope the doc to that focus instead of summarising everything.
- Don't write the handoff into the repo — it lives in /tmp deliberately, so a fresh checkout doesn't carry stale handoffs.
- Compact handoffs (< 1 page) beat exhaustive ones — agents skim summaries, not novels.
- Mention session-specific state (env vars set, files opened in editor, db migrations in progress) that wouldn't be in commits or issues.

---
Generated by SkillMake from https://github.com/mattpocock/skills/blob/main/skills/productivity/handoff/SKILL.md on 2026-05-12T18:05:07.120Z.
Verify against source before relying on details.

File: ~/.claude/skills/mp-handoff/SKILL.md