AI coding workflow

The handoff skill — passing context between agent sessions

A handoff skill takes a slice of one agent session, compresses it into a disposable markdown file, and passes it to a fresh session — so you keep the original conversation pure instead of clobbering it with /compact.

Creator: Matt PocockRuntime: 12 minVideo published: May 21, 2026222.3K views when summarized

Watch on YouTube

TL;DR

The short version

Context windows have a smart zone and a dumb zone; Pocock starts feeling the dumb zone around 120k tokens, far below the advertised million.
/compact" rescues a single long session by summarising it back into the smart zone, but it leaves sediment layers and can only continue one thread.
Handoff instead writes a markdown file capturing just the slice you want, so the original session stays pure and a fresh session picks up the rest.
Passing a handoff out and back creates a DIY sub-agent — prototype in a throwaway session, compress the learnings, hand them back to the planner.
Because it's plain markdown saved to the OS temp directory, the handoff is disposable and portable across Claude Code, Codex, or Copilot CLI.

01 · The skill

Too simple to need a skill, used constantly anyway

Pocock noticed himself doing something clever with agents that felt too trivial to package — then shipped it as a skill anyway, under skills / productivity / handoff, to see how often he'd reach for it. He reached for it a lot. The whole thing is a few lines of markdown: write a handoff document summarising the current conversation so a fresh agent can continue the work, and save it to the OS temp directory, not the workspace.

The entire `handoff` SKILL.md — description, an argument hint asking what the next session is for, and five short rules. The skills repo it lives in is approaching 100,000 stars.00:00:46

I'm constantly thinking about how to package my instincts and coding practices into reusable skills.— Matt Pocock

02 · Why

The context window has a smart zone and a dumb zone

Every tool call, file edit, and reply fills the context window. Claude Code advertises a million tokens, but early tokens get better answers — fewer tokens mean fewer attention relationships, so the agent's focus isn't diffuse. As the conversation grows, responses get dumber. Pocock says he's never reached 800k; he starts feeling the dumb zone around the 120k mark.

The window is split: a usable early stretch and a "Dumb Zone." The practical budget is roughly 120k tokens, not the million on the box.00:02:20

The real budgetA million-token window doesn't mean a million smart tokens. For proper work you have about 120k to spend, so you have to be aware of context at all times.

03 · /compact

Rescues one session, but leaves sediment

The built-in answer to the dumb zone is /compact: summarise the long conversation and drop it back near the start of the window. There's often an auto-compact buffer that fires automatically near the end. The summary is usually a list of referenced files, what you said, and the general tone — pasted in as a nugget at the top of the new session. Keep compacting and you build up sediment: layers of previous conversations stacked inside the window.

Repeated compaction leaves striped layers — each band a previous conversation referenced by the next. Inefficient, but useful for barrelling on the same debugging problem.00:04:18

Where compact fitsCompact is genuinely good for one long-running session — try options, hit a wall, compact to save state, try more. It just can't compact into another session.

04 · The move

Hand off a slice, keep the original session pure

The thing compact can't do: spin off a side task without contaminating the current thread. Say you spot a refactor that's out of scope. Extending the session dilutes it and pushes you into the dumb zone; compacting clobbers the progress you've made. What you actually want is to take just the slice that pertains to that side task, hand it to another session, and let the two run independently.

Session 1 stays intact; a `handoff.md` carries one slice down into Session 2. The two then run on their own.00:05:58

Take just the slice that pertains to this extra bug fix, hand it off to another session, and then these two could just run independently.— Matt Pocock

05 · In practice

Hand off mid-grill to file the side task

Pocock most often uses handoff while "grilling" — a session where the agent interrogates him to plan features, here for his software factory Sandcastle. Only two questions in, he notes that iterations and the completion signal might belong on a separate API, and hands that off. The move sharpens the current session too: declaring the side task out of scope collapses the question he was stuck on. The handoff file becomes the focus for a later session — file a GitHub issue, then eventually design the split.

Mid-grill in Sandcastle: naming the reason for the handoff and exactly what goes in the document. Stating "that's out of scope, we'll pick it up elsewhere" resolves the current question.00:06:58

Always state the whyPocock always describes the purpose when handing off — he can't see how you'd write a good handoff otherwise. Dictation makes it easy: blast out the reason and go.

06 · The pattern

Hand off to prototype, then hand the learnings back

Grilling surfaces two kinds of questions: known unknowns the agent can just ask about, and things you need to see — a UI prototype, a tricky bit of logic. So Pocock hands off from the grill to a prototype branch (the window communication, the tldraw SDK integration). That prototype session ballooned to 169k tokens — far bigger than would have fit in the grill. Then he hands the learnings back: take anything non-obvious not captured in the prototype itself and give the planner a handoff document.

The prototype session writing a handoff back to the grilling session that spawned it — pitching the prototype learnings into a temp markdown file.00:08:36

A DIY sub-agentSession does work, hands off to a child, child compresses its learnings and hands them back to the parent. That's a sub-agent built by hand — a dedicated context window for one task, results passed up.

07 · Why markdown

Disposable, redacted, and agent-agnostic

The rest of the skill is reasoning, not magic. A "suggested skills" section lets the new session auto-invoke what it needs (grill with docs, diagnose, prototype) so you don't have to remember. "Don't duplicate content" keeps the files from bloating — point at PRDs and issues by path or URL instead. Save to the OS temp directory because these files are disposable, not documentation to rot in your repo. Redact API keys, passwords, and PII. And because it's just markdown — not native agent state — the first session can be Claude Code and the next can be Codex or Copilot CLI, which makes adversarial cross-agent review trivial.

The skill's rules in the editor: suggested-skills, no duplicated content, redact secrets, and treat passed arguments as the next session's focus.00:10:30

These handoff files are disposable. They are not something to be kept around for a long time to rot in your codebase as documentation.— Matt Pocock