The session was past 140,000 tokens when I noticed Claude had started contradicting decisions we had locked in two hundred messages earlier. The window was technically still open; practically, the model was working in fog. The fix was not a bigger window and it was not /compact. It was a habit change: split the work into purpose-scoped sessions and pass a small Markdown handoff file between them, so every session runs inside its own sharp early-context zone instead of pretending degradation does not exist.
That is the thesis of this post, stated up front because it is the answer to the query that probably brought you here: compaction is a memory band-aid for one long thread; the handoff skill is a structural tool that splits threads so each one fits naturally. I use both, but I use them for different jobs, and confusing the two is the mistake I made for weeks.
Big Context Windows Made This Problem Worse, Not Better
Claude's large context windows sound like a solved problem: pour everything in, let the model sort it out. Anthropic's own documentation acknowledges that recall degrades as context fills, and my experience running long sessions says quality slips well before the ceiling, long before anything errors.
I think of every window as two layers. The smart zone: system prompt, fresh exchanges, the early tokens where attention is sharp. The dumb zone: the stale middle, still "in context," not getting the weight you think it is. Sessions that cross into the dumb zone do not announce it. Replies stay confident. But decisions get quietly reversed, tool selection goes mushy, and code starts looking like a composite of three designs you had almost converged on. I documented what that looks like at depth when I stress-tested Claude Code's 1M context over 30 days: the failure mode at scale is rarely the hard limit; it is drift.
The handoff skill's one-line job: split work across sessions so each stays in its smart zone.
What the Handoff Skill Actually Does
I run a handoff skill from my shared skills directory, and its own frontmatter states the job better than any paraphrase: "Compact the current conversation into a handoff document for another agent to pick up." The details that make it work, quoting the actual behavior of the skill on my machine:
- It is purpose-tailored, not a generic summary. The skill takes an argument, literally hinted as "What will the next session be used for?", and shapes the document for that focus. A handoff for "continue the API design" and one for "prototype the UI we sketched" come out different even from the same parent session.
- It writes a real Markdown file to a temp path (via
mktemp), so it never clutters the repo and I can open, edit, or redact it before passing it on. Try auditing what/compactkept; you cannot. - It points instead of duplicating. The skill's own rule: do not duplicate content already captured in other artifacts, PRDs, plans, ADRs, issues, commits, diffs; reference them by path or URL. This is the anti-drift rule. Paraphrasing an issue you already wrote precisely is how truth erodes between sessions.
- It suggests skills for the next session. The outgoing session knows whether the receiving one will want TDD, brainstorming, verification, or worktrees, and writes that hint into the doc, so the fresh session arrives pointed at the right toolbox.
A good handoff ends up around 400-600 words. Small enough to read in a minute, complete enough to act on immediately.
Handoff vs /compact: The 80 Percent Question
| Dimension | /compact |
handoff |
|---|---|---|
| Topology | One long session, shortened | Multiple purpose-scoped sessions |
| Compresses | The whole history | Only what the next session needs |
| Output | Opaque, back into the same context | Editable Markdown file on disk |
| Portability | Locked to the session | Works across Claude Code, Codex, any agent that reads text |
| Artifacts | Re-summarizes them | References them by path |
| Best for | Continuing one coherent task, less verbosely | Side-quests, spikes, plan/build splits |
The heuristic that settles every case for me: will the next stretch of work share more than 80 percent of the context currently in the window? Yes: compact. No: handoff. Most of the times I used to reach for compact, the honest answer was no.
The Three Patterns That Earned Permanent Slots
The mid-session refactor temptation. Deep in feature A, I spot something misdesigned in a shared module. Old me fixed it inline and paid for it with twenty messages of refactor debris still in the window when feature A resumed. New me writes a two-line handoff ("split path validation from formatting in normalize(); tests already cover it; skills: TDD") and keeps feature A's session clean. This is the cheapest workflow win I have gotten from any tooling change this year.
Spikes that branch off a review session. When a pressure-testing session surfaces a question that needs 90 minutes of prototyping ("does the renderer actually handle nested admonitions through the CMS?"), the spike gets its own session via handoff, and, this is the part that surprised me, the handoff is bidirectional. The prototype session writes its findings back as a handoff, and the review session ingests three distilled paragraphs instead of 90 minutes of trial and error.
Planning split from building. Planning sessions accumulate dozens of "what if" branches that do not survive the decision. Build sessions accumulate test output and diffs irrelevant to the spec. Run them separately: planning produces a handoff of locked decisions and open questions; the build session executes and hands back anything that invalidates a decision. Loop until the build has nothing to push back. This is the same plan-then-build rhythm from my daily slash-command workflow, made portable across windows.
What Goes in a Good Handoff
Nine sections, most of them one to five lines: the goal (one sentence), pointers to ADRs and issues (never their contents), current state (branch, files touched), locked decisions the next session must not relitigate, the two to five genuinely open questions, dead ends as one-liners, suggested skills, a quick-start (first command, first file), and a note of what was redacted.
Two mistakes to avoid, learned the annoying way. Do not restate what is in the issue; say "see issue #142." And do not make the handoff sound more finished than it is. The next session will discover the open questions anyway; you want it discovering them in the smart zone of a fresh window, not after it has committed to a wrong direction. An unexpected side effect: my ADRs got sharper once handoffs started referencing them, because I knew a cold session would read them literally.
When the Work Outlives the Session: Manifests
Here is the insight I have not seen anyone else write down, and it comes from a project where handoffs alone stopped scaling. Last month I rewrote 84 blog posts on this site across seven batches and many separate Claude Code sessions spread over days. A handoff file is perfect for passing work to the next session. It is the wrong tool when the work will outlive ten sessions, survive machine restarts, and needs to be resumable by any future session cold.
For that, the handoff grows up into a durable resume manifest: a JSON status file in the repo (mine lived at storage/app/seo-rewrite/REWRITE-STATUS.json) listing every unit of work with a DONE or PENDING state, plus a tiny script whose only job is flipping a unit to DONE. Every fresh session starts the same way: read the manifest, take the next PENDING item, do it, mark it, stop. No session needs to know what any previous session did beyond what the manifest records. When a session died mid-batch, nothing was lost; the next one picked up at the exact boundary.
The general rule I extracted: handoffs for tasks, manifests for campaigns. A handoff carries intent and nuance between two adjacent sessions. A manifest carries state across an arbitrary number of sessions with zero nuance and total reliability. Big multi-session jobs need both: the manifest says what is left, and a handoff says how the last session was thinking. The file is the orchestrator; no framework required.
Why Markdown Is the Load-Bearing Choice
A handoff generated by Claude Code can be read, unmodified, by Codex CLI or any other agent that reads text. That portability is what enables cross-agent patterns: Claude Code produces work plus a handoff, a differently-trained model picks it up for adversarial review, and its critique comes back as another handoff. Each agent stays in its smart zone; the Markdown file is the only thing crossing boundaries. That flow is half of why my Claude Code and Codex same-repo setup works at all.
Markdown also buys you review-before-send. Every handoff gets a 30-second scan: did redaction catch the secrets, are the locked decisions actually locked, did a listed dead-end turn out to be the right path. You cannot do that scan on an opaque summary.
What Handoff Is Not
It is not a substitute for in-session discipline; a session sprawled across six topics produces a sprawled handoff. It is not for jobs that fit in one short session; the format has overhead, and ceremony is the enemy. It does not fix vague upstream documents; pointers are only as good as what they point at. And it is not verification; a handoff says "we got here," and the receiving session still has to run the tests. On the cost side, keeping sessions short and scoped pairs naturally with keeping them cheap, which is the territory of my caveman token-optimization writeup.
Quick Answers
What is the handoff skill in Claude Code?
A skill that compacts the current session's relevant state into a purpose-scoped Markdown file (goal, decisions, open questions, pointers to artifacts, suggested skills) that a fresh session, or a different agent entirely, reads to continue the work without inheriting the bloat.
When should I hand off instead of compacting?
When the next stretch of work shares less than roughly 80 percent of the current window's context: unrelated refactors, prototyping spikes, and plan-to-build transitions. Direct continuations of the same task are compact territory.
Does this work across different coding agents?
Yes. The output is plain Markdown, portable to Codex CLI or any agent that reads text, which is what makes cross-agent review workflows practical without glue code.
The 80 percent question is the one line here worth memorizing; compaction, handoffs, and manifests are all just implementation detail hanging off it. The prompts I actually reuse for session scoping, planning handoffs, and resumable multi-session jobs sit alongside hundreds of others in my prompt library, free to lift and worth rewriting into your own vocabulary.
