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.mdlog so a fresh session can orient itself in seconds.
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.
When a session wraps up, the skill produces four artifacts:
- A handoff document — minimum-token context transfer for the next agent.
- A
STATUS.mdlog entry — appended to the project root, never overwritten. - A snapshot commit — repo state matches the handoff exactly (clean starting point + restore point).
- 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.
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.
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.
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.shinstall.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/handoffThe 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 readSTATUS.md
A typical handoff plays out like a four-line transcript:
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.
See examples/handoff-example.md for a real (sanitized) handoff document, and examples/STATUS-example.md for a sample STATUS.md log.
- 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)
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.shcopiesSKILL.md+scripts/status-check.shinto 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.shunder 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.mdleft over from an abandoned mode-split refactor. - Doc neutrality — Phase 1 now looks for
AGENTS.md(Codex governance) alongsideCLAUDE.md, and a maintainer note inSKILL.mddocuments 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-handofftoagent-handoff-skillso the name matches the cross-tool Claude Code + Codex CLI positioning.
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/.7sub-steps) and thedescriptionnow names it as mandatory. - Non-Negotiables block + Completion Checklist — the handoff is "done" only after a checklist that fails unless
STATUS.mdshows today's date. - Read-only
scripts/status-check.shhelper — 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 statusreview to avoid blanketgit add -Asweeping in secrets or unrelated files. Never pushes. - Safer compression — outright deletion of archived entries now requires confirming the content is already in git history.
- Removed unrelated dev artifacts (internal handoff notes, TTS experiments) from the published repo
- Renamed
marketing/→assets/and updated README image links
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)
- 5-phase handoff investigation
- STATUS.md append-only log
- Snapshot commit
- Copy-paste prompt generation
- Fresh session orientation via STATUS.md
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.shunder whichever tool directory exists. Runscripts/install.shto 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.
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.
MIT — see LICENSE.