Handoff Skill Workflow: Beating Context Slowdown in AI Coding Agents

⬅️ Back to Projects

Overview

mattpocock/skills (86k+ stars) is the most widely-used collection of agent skills for Claude Code, Codex, and other coding agents. The handoff skill is the one I use most often. A simple but brutally effective tool that compresses the current conversation into a document for another agent session to pick up.

The concept is straightforward: condense what you’ve done, what’s left, and the key context into a markdown file, then start fresh. But the impact on long coding sessions is dramatic.

Why Handoff Matters

I noticed a pattern with Codex specifically: as the context gets longer, the response speed drops dramatically. Not just interface lag, as the actual model return speed degrades. GPT’s context window is relatively smaller than Claude’s or Gemini’s, so around 70-80% of the way through a long task, things slow to a crawl.

The natural response is to let the agent’s built-in auto-compression handle it. But auto-compression is reactive; it kicks in when you’re already past the threshold, and the compressed output loses nuance. Handoff is proactive.

By deliberately compressing the session at the right moment into a handoff file, then starting a new session, I get:

  • Full speed: The new session starts with a clean, lean context
  • Better compression: I control what gets summarized and what gets referenced by path
  • No lost work: The handoff document captures intent and progress, while existing artifacts (PRDs, plans, commits, diffs) are referenced rather than duplicated

How the Skill Works

The handoff skill (from mattpocock/skills) defines a single agent command:

  1. Call it with a description of what the next session will focus on
  2. The agent writes a handoff document to a temp file (via mktemp -t handoff-XXXXXX.md)
  3. The document summarizes progress, suggests skills for the next session, and references existing artifacts instead of duplicating content
  4. Start a new agent session and feed it the handoff file
/handoff "Implement the remaining API endpoints and add error handling"

The skill is deliberate about what it doesn’t do: it won’t duplicate content already captured in other artifacts. If you have a PRD, a plan doc, or git commits, it references them by path or URL instead of re-summarizing. The result is a lean, reference-heavy handoff that fits in a small window.

My Workflow

I use handoff as a planned break point rather than an emergency recovery:

  1. Watch for the slowdown: Around 60-70% through a task, when the agent starts taking noticeably longer per response
  2. Trigger handoff: /handoff "Continue with [specific remaining work]", the argument tailors the document to exactly what’s next
  3. Save and close: The handoff file contains everything the next session needs
  4. New session: Start fresh with cat the-handoff.md | codex or similar
  5. Full speed immediately: The new session responds fast because its context is lean

The result is that a task that would crawl through its final 20-30% at half speed instead finishes at full speed from start to end.

Relation to /goal Mode

The handoff concept is essentially manual chain-of-thought with state transfer. Codex’s /goal mode, which recently shipped, operates on a similar principle: break long tasks into sub-sessions with compressed state passed between them. The difference is that /goal automates the split, while handoff gives you manual control over when and how the compression happens.

I prefer handoff for the control. When I’m deep in a complex refactor, I know exactly which context matters and which is noise. The skill lets me shape the handoff document to match.

Why This Workflow Rocks

  • Beats context slowdown: New sessions respond at full speed immediately
  • Manual control: You decide what to compress and what to reference
  • No auto-compression loss: Avoids the nuance drop of automatic context trimming
  • Lean handoffs: References existing artifacts instead of duplicating them
  • Works across agents: The handoff file is plain markdown; use it with Codex, Claude Code, OpenCode, or any agent
  • Simple: No infrastructure, no plugins, no config

🔗 GitHub: github.com/mattpocock/skills

Crepi il lupo! 🐺