handoff: Move Context Between Agent Sessions

Install this skill:

npx skills add mattpocock/skills skill=handoff -y -g

Source: mattpocock/skills/handoff

What It Does

The /handoff skill compresses your current agent session into a markdown document that can be passed to another agent session. This lets you split concerns across independent sessions while keeping each one focused and smart. The document contains:

• The purpose of the next session
• Relevant context from the current session
• Suggested skills to invoke
• Pointers to existing artifacts (not duplicated content)

The document is saved to your OS's temporary directory - these are disposable working documents, not permanent documentation.

When to Use Handoff

Use handoff when you:

• Notice an out-of-scope task during your current session
• Want to prototype something without bloating your current context
• Need to pass work between different AI coding tools
• Want to keep your current session pure and focused

How It Differs From /compact

Before diving into usage patterns, it's worth understanding how /handoff differs from the built-in /compact feature that most AI harnesses provide.

If you dig this kind of content, check out my cohort course: AI Coding for Real Engineers, starting March 30th. It's a focused two-week program for shipping quality code, not slop.

Understanding Context Windows and /compact

When you're in a coding session, conversing with an agent, watching it make tool calls and edit files, your context window fills up with tokens, more and more of them.

In Claude Code, the context window is enormous: 1 million tokens. But here's the critical detail: there's a smart zone and a dumb zone within it.

The Smart Zone vs. The Dumb Zone

Early in the context window, you get much better performance from the agent because attention relationships aren't strained. With fewer tokens, there are fewer attention calculations, so the agent's focus isn't diffuse - it can focus better.

As your conversation develops, responses gradually get dumber. By around 120,000 tokens, I personally feel like I've entered the dumb zone. This means that even though Anthropic advertises massive context windows, you realistically only have about 120k tokens for smart work.

You need to budget efficiently and stay aware of your context window at all times.

How /compact Recovers Intelligence

When you start hitting the dumb zone, what do you do? The answer is /compact.

/compact takes a large conversation and summarizes it, moving you from the dumb zone back to the smart zone. Most AI harnesses also include an auto-compact buffer that kicks in when you're deep in the dumb zone, automatically summarizing your conversation into a new session.

These summaries typically include:

• Referenced files
• Key conversation points
• General tone and context

The summary is then included as context at the start of the new session. As you continue compacting, you build up layers of previous conversations - like sediment.

This is useful for long-running, single-threaded work, especially debugging. You can compact all the options you've tried, then keep trying different approaches without losing history.

Why /handoff Differs From /compact

I love /compact for creating long single sessions, but I started wanting to do something different with it.

Picture this: you're in one session working on a feature, but you notice a refactoring opportunity - something totally out of scope but important. What are your options?

1. Extend your current session - You'd dilute your context, half-working on two things, hitting the dumb zone before finishing your initial goal.

2. /compact - You'd clobber all progress on your current session.

3. Handoff - You take just the slice of context relevant to the refactoring, hand it off to another session, and keep your current session pure.

That third option is what I wanted. Handoff lets you split concerns across independent sessions while keeping each one focused and smart.

Common Handoff Patterns

Handoff During Grilling Sessions

Use /handoff when you're in a grilling session and notice something out of scope:

• Sharpen your current session - Declaring something out of scope focuses the grilling on what's actually relevant
• Create focused work for later - The handoff document captures just what's needed for the separate task
• Keep context clean - Your grilling session stays pure and completes faster

Handoff to Prototype

When grilling, you'll encounter two types of questions:

• Known unknowns - Things the agent can ask you about directly
• Things you need to see - UI interactions, complex logic, or architectural decisions that need prototyping

For the second category, hand off to a prototype session:

1. During grilling, identify what needs prototyping
2. Use /handoff to create a focused prototype document
3. Build the prototype in a separate session (can be 100k+ tokens)
4. Create another handoff document passing learnings back
5. Return to the grilling session with compressed insights

This creates a DIY sub-agent pattern: use a full context window for exploration, compress learnings, and pass them back to the parent session.

Cross-Agent Workflow Benefits

What's elegant about using a markdown document instead of relying on native agent features is portability.

Your first session might be Claude Code, but you can pass the handoff document to Codex, Copilot CLI, or any other coding agent. This opens possibilities for:

• Adversarial review - Different agents reviewing each other's work
• Tool diversity - Using the best tool for each specific task
• Flexibility - Not locked into one harness or vendor

Skill Design Decisions

Let me walk through the final design principles of the handoff skill so you understand the reasoning:

Suggested Skills Section

Include a suggested skills section in the handoff document. I do this because skills define the flavor of a session. By suggesting skills like /grill-with-docs, /diagnose, or /prototype, the next agent session can immediately invoke them without you having to think about what's needed.

Avoid Duplication

Do not duplicate content already in other artifacts. I found these documents got bloated fast, repeating things already in markdown files, GitHub issues, or other resources. Use pointers instead - reference the existing content rather than duplicating it.

Save to Temporary Directory

Save handoff files to the temporary directory of the user's OS. These files are disposable. They're not something to keep in your codebase's documentation, rotting over time. They're working documents for context transfer, nothing more.

Redact Sensitive Information

Redact any API keys, passwords, or PII. These documents shouldn't contain secrets floating around in random markdown files.

Tailor to the Next Session's Purpose

If the user passes arguments - describing what the next session will focus on - treat those as the guide for what to include. I can't imagine writing a good handoff document without knowing what the next agent will actually do. That's why I always describe the purpose when I invoke the skill, and dictation makes this effortless.