Handoffs Pattern in Claude Workflows: Two-File Split vs One-Doc Summary

Long Claude sessions degrade from context decay. Handoffs solve this by compressing key information into a document and starting a fresh agent. Two implementations are now being discussed in the community: Matt Pocock's /handoff skill and an alternative two-file split approach used in the APM multi-agent framework.

Matt Pocock's Handoff Skill

Pocock's skill compacts the conversation into a single document. It points at existing artifacts instead of restating them, and the next agent picks up from there. It also chains between threads: /grill-with-docs → /handoff → /prototype → /handoff back. The repo is available at mattpocock/skills.

Two-File Split Approach (APM Framework)

An alternative approach, built into the APM multi-agent framework for Claude Code back in May 2025, splits the handoff into two artifacts:

• Persistent narrative file — records what was done, decisions made, and why. This lives in the project and leaves a durable trail.
• Ephemeral prompt — tells the incoming agent how to rebuild context from the codebase and the persistent narrative file.

The key difference: the incoming agent reconstructs from durable project state (codebase + narrative), not just the compressed chat conversation. Persisting the narrative also makes it visible when multiple agents are involved, so you can track which agent is working off a summary vs firsthand context. This makes context gaps easier to manage.

The author opened an issue on Pocock's repo with these ideas: mattpocock/skills#235.

Key Questions

• Is a single compressed document enough for handoffs?
• Or does the two-file split (persistent narrative + ephemeral prompt) provide better context reconstruction and multi-agent traceability?

The discussion is ongoing. Both approaches are valid depending on whether you need a quick resume or long-running multi-agent workflows with context gap management.