Handing Work Between AI Agents Without Re-explaining Everything: project-handoff

Handing Work Between AI Agents Without Re-explaining Everything: project-handoff

Reconstruct an afternoon you've probably lived through. In the morning you push a feature forward with Codex: the architecture trade-offs get talked through, a gnarly dependency pitfall gets smoothed over, one approach gets explicitly rejected. In the afternoon you switch to a different client to continue — and the new session knows nothing. What's the goal? Where did things stop? Which decisions are settled? You either re-narrate everything from scratch, or watch the agent enthusiastically rebuild the approach you rejected hours ago and step on the exact rake you already stepped on.

project-handoff-skill turns handoff into a set of files inside the project: every new session checks the handoff state before touching anything. It's bound to no particular client — it only relies on the AGENTS.md open convention that every agent already understands.

The skill comes from my own routine: five or six agent clients in rotation, every handoff done by re-explaining to a goldfish. I tried letting agents write handoff notes themselves; the problem was nobody could hold the notes to a shape — some ballooned until they ate the context window, some were written once and never read again. So the discipline itself became a skill: one setup question, records written to disk automatically, size on a hard budget.

Five situations where you want it

1. You switch between clients all day

Codex in the morning, ZCode in the afternoon, Kimi Code CLI at night — and you don't want to re-brief any of them. After install, one sentence sets it up: "Set up project-handoff mode for this project." It installs at user level and drops a toggle file in the project root. From then on every new session self-checks: never configured → asks once whether to enable; already configured → silently keeps going, never asks again.

2. The project spans days or weeks

You want to resume, not excavate chat history to reconstruct progress. Once enabled, the project gains a HANDOVER.md — goals, current progress, settled decisions, pitfalls — and every new session reads it before working. What's done, what's next, what must not be touched: visible at a glance.

3. You're forced to switch tools mid-flight

Quota exhausted, context window full, a provider having a bad day — the switch isn't optional, and the new tool needs to know immediately where things stand and what's off-limits. This is exactly the handoff file's home turf: it doesn't depend on any client's session memory. The files live in the project; anyone can read them.

4. You've been burned by "I forgot to mention one thing"

Forgot to say approach A was rejected → the agent rebuilds it. Forgot to say that dependency is a trap → the agent steps in it again. Handoff records pin these negative facts in plain sight — rejected approaches, dead-end paths, reproduced pitfalls — where the new session sees them before starting, instead of after the collision.

5. Several people (or agents) rotate through one project

You log off; whoever picks it up next — human or agent — needs the same "where we are" picture. The handoff file sits in the repo, readable by both. Both sides of the relay are looking at the same facts.

When NOT to install it

The honest part of a recommendation is the reverse list. If you use exactly one client and never switch, that client's own session memory is enough and handoff files are pure overhead. One-off script repos have no "next session" to hand off to. And if agents are entirely managed for you and you never touch the workflow, extra files and prompts will only add noise.

How it stays contained

The three classic failure modes of agent-written handoff notes — unbounded growth, write-once-never-read, uncertainty about what belongs — each get a gate:

• Bounded footprint: handover records over 8KB / 300 lines auto-slim down to the three most recent sections, the rest archived. Run records keep 20 entries per agent; older ones compress into an archive index. The agent normally reads only small files.
• Self-explaining footprint: one sentence — "run a health check on the handoff setup" — has the agent execute --status: what this is, whether it's on, which files are its own, how to turn it off, how to remove it. One command, full answer.
• Heartbeat lock for orphans: a session that dies halfway without closing out gets auto-flagged as "interrupted, awaiting pickup" after a timeout — the next agent sees it immediately.
• Privacy red line: hooks record event names, timestamps, and session IDs only — never prompts, replies, or command contents. A dedicated test pins this promise, and 45 replay cases run on macOS + Linux CI.

Install and use

# Option 1: skills CLI (recommended) npx skills add kelegele/project-handoff-skill # Option 2: drop it into a skills dir manually (dir name must be project-handoff) # Cross-agent: ~/.agents/skills/ ZCode: ~/.zcode/skills/ Codex: ~/.codex/skills/ # Update npx skills update project-handoff 

After install, two phrases drive everything:

Set up project-handoff mode for this project

Run a health check on the handoff setup

Daily service commands (all plain speech; the agent runs the scripts):

Three quick answers

Does it work with an agent it's never heard of? Yes. The shared artifacts rely only on the AGENTS.md convention; any compatible client reads the same files. Automatic recording is a bonus, not a dependency.

Will it keep asking whether to enable? No. Asked once, then silent while config is valid. If config breaks, it names the specific problem instead of pretending nothing was ever configured.

How do I remove it completely? --status prints the full list: delete the project toggle file and docs/execution/, remove the handoff section from AGENTS.md, delete the skill directory. No residual dependencies anywhere.

Start small

Pick a project where you genuinely switch between tools. Install it, enable handoff, work half a day normally, then continue once from a different client. You'll see immediately how much re-explaining the file just saved you.

Repo on GitHub; issues and ideas welcome. It's the other half of the same puzzle as agentsmd-skill: agentsmd turns lessons into rules (scene guide, design reasoning), project-handoff carries progress to the next session — one makes the AI remember how to work, the other makes it know where you left off.