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

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

This release turns handoff into a single-source, cross-tool skill for both Claude Code and Codex CLI.

Highlights

• One source of truth: SKILL.md + scripts/status-check.sh
• scripts/install.sh now syncs the skill into both ~/.claude/skills/handoff/ and ~/.codex/skills/handoff/
• Phase 6 helper path now resolves under either Claude or Codex install paths
• Phase 1 now checks both CLAUDE.md and AGENTS.md
• Codex install brought up to parity with the latest handoff flow
• Repo renamed from claude-skill-handoff to agent-handoff-skill to reflect cross-tool scope

Verification

• Claude and Codex installed copies verified byte-identical
• status-check.sh verified from both install paths
• Secret scan passed

Install

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

v1.2.0 — Reliable STATUS.md updates + copy-paste prompt

Why this release

Two steps were getting silently skipped when running /handoff: the STATUS.md update and the copy-paste prompt for the next session. The feature text existed, but it was structured so agents trailed off before reaching it. v1.2.0 makes both impossible to skip silently.

What changed

STATUS.md now actually updates

• Promoted from a throwaway Phase 5.5 to a first-class Phase 6 (MANDATORY); the skill description now names it.
• Non-Negotiables block up top + a Completion Checklist that fails unless STATUS.md shows today's date.
• New 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 (printed in the reply, not saved to a file), with a concrete template to mimic.
• Reinforced in both the Non-Negotiables and the Completion Checklist.

Hardening

• Snapshot commit (Phase 7): git-repo guard, mandatory secret scan before staging, and a git status review to avoid blind git add -A sweeping in secrets/junk. Never pushes.
• Safer compression: deleting archived entries now requires confirming the content is already in git history.
• Clean Phases 1–8 (removed the .5/.7 sub-step smell).

Upgrade

cd ~/.claude/skills/handoff && git pull

No breaking changes — existing STATUS.md files keep working.

Full diff: v1.1.1...v1.2.0

v1.1.0 — STATUS.md compression + visual output

What's New in v1.1.0

Three-layer STATUS.md compression

STATUS.md now uses ▲ Current / ■ Milestones / ▼ Archive format.
Auto-compresses when file exceeds 100 lines or 15 milestones.
AI reads only Current + Milestones (~30 lines) by default.

Clack-style visual output

Handoff process now renders with banner, guide bar (┌│└), diamond indicators (◇◆), and summary box. Scannable and satisfying to watch.

Passive compression check

Fresh session orientation offers to compress oversized STATUS.md without auto-doing it.

Changed

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

Upgrade

git -C ~/.claude/skills/handoff pull

v1.0.0 — Initial public release

First public release of the handoff skill for Claude Code.

What this skill does

• Generates an intelligent context handoff document for the next agent in a fresh conversation, with the smallest possible token cost.
• Maintains a running STATUS.md log at the project root so a fresh agent can orient itself even without a handoff prompt.
• Creates a snapshot commit so the next agent has a clean starting point and restore point.
• Outputs a copy-pasteable prompt for the new chat.

Install

git clone https://github.com/phat-po/claude-skill-handoff ~/.claude/skills/handoff

That's it. The skill is now available in any Claude Code session.

Usage

Trigger via the /handoff slash command, or natural phrases like:

• handoff / hand off
• pass to next agent / next agent
• session done / stage done
• wrap up for next agent

When opening a fresh chat, just ask "where are we?" or "帮我看一下这个项目进行到什么程度了" — the skill auto-reads STATUS.md to orient itself.

Why this exists

At the 2026-05-16 vibecoding hackathon Bottleneck Wall, multiple participants independently wrote down the same pain point on a sticky note:

"一个大任务跑到一半 token 就烧到 80% 了，AI 开始变笨或者直接断掉，我也不知道怎么把进度交给下一个 session 继续"

"每次开新对话都要重新跟 AI 解释一遍项目背景，昨天花三小时 debug 出来的结论它今天全忘了"

"The previous context doesn't get carried through the next conversation all the time."

This skill is the answer.

See also

• SKILL.md — full skill spec
• examples/handoff-example.md — sanitized handoff doc example
• examples/STATUS-example.md — sample STATUS.md log

License

MIT