Agent Handoff Skill

handoff — Intelligent Context Handoff for Claude Code & Codex CLI

> One skill for Claude Code and Codex CLI that lets you switch sessions without losing context. > Generates a minimum-token handoff doc for the next agent and maintains a project-root STATUS.md log so a fresh session can orient itself in seconds.

---

The pain

If you've vibecoded for more than a few weeks, you've hit this wall. Three quotes from the 2026-05-16 Hackathon Bottleneck Wall, where attendees wrote their biggest AI-coding pain on sticky notes:

This skill is the answer. It treats session boundaries as a first-class engineering problem — not a hope-it-works moment.

---

What you get

When a session wraps up, the skill produces four artifacts:

1. A handoff document — minimum-token context transfer for the next agent.
2. A STATUS.md log entry — appended to the project root, never overwritten.
3. A snapshot commit — repo state matches the handoff exactly (clean starting point + restore point).
4. A copy-paste prompt — drop into the next conversation, that's it.

It's not a template. The skill investigates what actually happened, figures out the minimum reading list, and writes a doc adapted to the specific situation.

---

The killer feature: STATUS.md

Every handoff appends one entry to a STATUS.md at the project root — append-only, never overwritten, so the file becomes a scrollable history of the project. The trick: the next time you open a chat and ask "where are we?" or "what's the status of this project?", the skill auto-reads the last entry plus git log --oneline -5 and orients itself in seconds. No handoff prompt required. Finding STATUS.md becomes the default first move.

Three-layer compression (v2)

As the project grows, STATUS.md stays fast. The file uses three layers:

| Layer | What's in it | AI reads this? | |-------|-------------|----------------| | ▲ Current | Full detail for the latest 1-2 sessions | Always | | ■ Milestones | One-line per completed milestone | Always (quick scan) | | ▼ Archive | Oldest compressed entries | Only on demand |

When the file exceeds 100 lines or 15 milestones, the /handoff skill automatically compresses older entries into one-line milestones — no manual cleanup needed. Git history preserves the detail if you ever need it.

---

Install

One source of truth, installed to both Claude Code (~/.claude/skills/handoff/) and Codex CLI (~/.codex/skills/handoff/):

git clone https://github.com/Phat-Po/agent-handoff-skill
cd agent-handoff-skill && bash scripts/install.sh

install.sh copies the skill into whichever of the two tools are present (a copy, not a symlink — so it keeps working even if the clone is deleted or lives on an external drive). Re-run it any time you edit SKILL.md to keep both tools in lockstep.

To verify, in a Claude Code or Codex session type /handoff or just say "wrap up for next agent" — it should trigger.

Claude Code only, you can also clone straight into the skills dir:

git clone https://github.com/Phat-Po/agent-handoff-skill ~/.claude/skills/handoff

---

Usage

The skill triggers on any of these:

• The slash command /handoff
• Phrases like handoff, hand off, pass to next agent, context handoff, next agent, session done, stage done, wrap up for next agent
• Fresh-session questions like "where are we?" / "what's next?" automatically read STATUS.md

A typical handoff plays out like a four-line transcript:

---

How it gets there

The skill is deterministic about process, not output — every handoff runs through the same fixed phases, ending in four mandatory artifacts (handoff doc, STATUS.md entry, snapshot commit, copy-paste prompt). The STATUS.md update is its own phase with a read-only helper that supplies the real date and the compression verdict, and a closing Completion Checklist that fails if STATUS.md doesn't show today's date — so it can't be silently skipped. For the complete spec, see [SKILL.md](./SKILL.md).

---

Example

See [examples/handoff-example.md](./examples/handoff-example.md) for a real (sanitized) handoff document, and [examples/STATUS-example.md](./examples/STATUS-example.md) for a sample STATUS.md log.

---

Anti-patterns it avoids

• Conversation transcripts (the next agent doesn't need to know what you discussed)
• Padding with boilerplate sections (empty "Constraints", "Database", etc.)
• Over-including the reading list (every extra file costs tokens)
• Assuming the next agent reads prior handoffs (each handoff is self-contained)

---

Changelog

v1.3.0 — Cross-tool: one skill for Claude Code + Codex CLI

Why: the skill had drifted into two divergent copies — the Codex install (~/.codex/skills/handoff/) was stuck at a pre-v1.2.0 version (STATUS update was an optional half-step, no status-check.sh helper, no completion checklist) plus orphaned references/ files from an abandoned refactor. Two copies guarantee drift. This release makes it one source of truth that runs identically on both tools.

• Single source, installed to both — scripts/install.sh copies SKILL.md + scripts/status-check.sh into both ~/.claude/skills/handoff/ and ~/.codex/skills/handoff/ (copy, not symlink, so it survives a deleted or unmounted-external-drive clone). Edit once, sync both.
• Portable helper path — Phase 6 Step 1 now resolves status-check.sh under whichever tool directory exists, instead of hardcoding ~/.claude/.... Works identically on Claude Code and Codex CLI.
• Codex install brought up to parity — replaced the stale copy and removed the orphaned references/{write,status,execute}-mode.md left over from an abandoned mode-split refactor.
• Doc neutrality — Phase 1 now looks for AGENTS.md (Codex governance) alongside CLAUDE.md, and a maintainer note in SKILL.md documents the single-source rule so the two installs can't silently diverge again.
• Repo renamed for the new scope — the public repo moved from claude-skill-handoff to agent-handoff-skill so the name matches the cross-tool Claude Code + Codex CLI positioning.

v1.2.0 — Reliable STATUS.md updates + hardening

Why: the STATUS.md update was numbered Phase 5.5 — a half-step that agents under context pressure routinely skipped. This release makes it impossible to skip silently.

• STATUS.md update promoted to a first-class phase (clean Phases 1–8, no more .5/.7 sub-steps) and the description now names it as mandatory.
• Non-Negotiables block + Completion Checklist — the handoff is "done" only after a checklist that fails unless STATUS.md shows today's date.
• Read-only scripts/status-check.sh helper — supplies the real date (date +%F, no more hallucinated dates) and a deterministic compression verdict (line + milestone counts), so compression triggers reliably instead of being eyeballed.
• Copy-paste prompt no longer goes missing — Phase 8 now marks the next-session prompt as REQUIRED chat output (not a file), with a concrete template to mimic, and it's listed in both the Non-Negotiables and the Completion Checklist. Previously it was described abstractly at the very end and frequently dropped.
• Snapshot commit hardened — git-repo guard, mandatory secret scan before staging, and git status review to avoid blanket git add -A sweeping in secrets or unrelated files. Never pushes.
• Safer compression — outright deletion of archived entries now requires confirming the content is already in git history.

v1.1.1 — Repo cleanup

• Removed unrelated dev artifacts (internal handoff notes, TTS experiments) from the published repo
• Renamed marketing/ → assets/ and updated README image links

v1.1.0 — STATUS.md compression + visual output

New features:

• Three-layer STATUS.md compression — ▲ Current / ■ Milestones / ▼ Archive. Auto-compresses when file exceeds 100 lines or 15 milestones. AI reads only Current + Milestones (~30 lines) by default.
• Clack-style visual output — banner, guide bar (┌│└), diamond indicators (◇◆), summary box. Handoff process is now scannable and satisfying to watch.
• Passive compression check in Fresh Session Orientation — agent offers to compress if STATUS.md is oversized, without auto-doing it.

Changed:

• Phase 5.5 now checks compression before appending (was append-only)
• Fresh Session Orientation reads only ▲ Current + top of ■ Milestones (was full file)

v1.0.0 — Initial release

• 5-phase handoff investigation
• STATUS.md append-only log
• Snapshot commit
• Copy-paste prompt generation
• Fresh session orientation via STATUS.md

---

Compatibility

One SKILL.md (plus scripts/status-check.sh), installed to both tools — same behavior whether you run in a terminal or a CLI:

• Claude Code — ~/.claude/skills/handoff/, triggers on /handoff
• Codex CLI — ~/.codex/skills/handoff/, identical frontmatter and auto-discovery
• The one tool-aware line is a helper-path resolver (Phase 6) that finds status-check.sh under whichever tool directory exists. Run scripts/install.sh to keep both in lockstep — never fork a per-tool copy (that is how the two installs drifted before v1.3.0).
• Other skill-format agents — the SKILL.md uses standard skill frontmatter and plain bash; should work anywhere the format is supported.

---

Background

Built and battle-tested across many vibecoding projects by Pohan. Open-sourced after the 2026-05-16 Hackathon Bottleneck Wall, where multiple attendees wrote down the same pain on sticky notes — the three quotes above.

---

License

MIT — see [LICENSE](./LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Phat-Po
• Source: Phat-Po/agent-handoff-skill
• License: MIT

Install and usage instructions live in the source repository linked above.