Open-Sourcing the handover Skill - Standardizing Context Handoff for AI Agents
Introduction
The hard part of AI-agent development is no longer just getting an agent to write code. The harder operational problem is making sure the next session knows what happened, what is safe to do next, and what must not be touched.
We have added a new handover skill to our open-source agent-skills project. Added in GitHub PR #58, the skill creates local session handovers with handover.md and .handover/, then lets future AI agent sessions resume from verified context.
Key Takeaways
- AI agent productivity depends on session continuity, not only single-turn answer quality
- The handover skill provides four modes:
write,boot,install, andstatus - Handovers are private local files by default and are checked against Git state before use
- The architecture combines AGENTS.md / CLAUDE.md startup guidance with Claude Code / Codex SessionStart hook adapters
Why Do AI Agents Need Context Handoff?
AI-agent work increasingly spans multiple sessions. Implementation, review, debugging, article writing, and PR response work often pause halfway, move to another agent, or resume the next day.
Without a handoff, the next session starts with avoidable uncertainty:
- Which branch, HEAD, and working tree state should it trust?
- Which exploration was already completed?
- Which files were intentionally left alone?
- Which commands failed and should not be repeated blindly?
- Which constraints came from the user rather than from the agent's guesses?
The issue is not just missing memory. The issue is unverified memory. A previous note can be helpful, but it becomes dangerous if the repository has moved on. The handover skill is designed around that distinction.
What Does the handover Skill Do?
The handover skill is a session-continuity protocol for AI agents. The current implementation includes the skills/handover/SKILL.md definition, English and Japanese templates, startup snippets, and Node.js helper scripts for Claude Code / Codex SessionStart hooks.
The core interface is intentionally small.
handover write
handover boot
handover install
handover statusEach mode has a clear responsibility.
| Mode | Purpose |
|---|---|
write | Leave a structured handover for the next session |
boot | Read an existing handover and verify it against the current repository |
install | Add startup guidance so future sessions check for handovers |
status | Inspect handover files, gitignore guards, startup guidance, and hooks |
Installation uses the same workflow as other agent-skills modules.
npx skills add anyoneanderson/agent-skills --skill handover -g -yHow Is the Architecture Implemented?
The handover skill is not a plain note-taking command. It is structured as a small verification architecture for resuming work safely.
User / agent instruction
|
v
handover skill modes
|-- write -> handover.md + .handover/current.md + state.json
|-- boot -> read handover + verify branch / HEAD / files
|-- install -> AGENTS.md / CLAUDE.md startup snippet
|-- status -> local health check
|
v
Claude Code / Codex SessionStart hook
|
v
short startup context: goal, next action, stop conditions1. Private Local Files by Default
Handovers are private by default. handover.md and .handover/ are local working notes, not artifacts that should usually be committed.
Before writing private handovers, the skill guards .gitignore with:
# Agent session handovers
handover.md
.handover/If handover files are already tracked, the skill warns the user but does not automatically run git rm --cached. That boundary matters: a session-continuity tool should not perform surprising Git mutations.
2. Separate Human Notes from Machine State
write creates human-readable handoff notes and machine-readable state metadata.
The human side is:
handover.md
.handover/current.mdThe verification side is:
.handover/state.jsonThe handover must include the current working directory, branch, HEAD, privacy mode, goal, current state, completed work, pending work, important files, commands run, known issues, decisions, next action, and stop conditions.
The most important rule is restraint: if the previous conversation does not provide enough information for a safe next action, the handover should say that explicitly instead of inventing one.
3. Verify Before Resuming
boot does not treat the handover as truth. It reads the handover, reads .handover/state.json if present, and checks it against the current repository state.
It verifies:
- whether the branch matches
- whether the HEAD matches
- whether referenced important files still exist
- whether the working tree status contradicts the handover
Only after that does it report the inherited goal, verified current state, stale or conflicting notes, and intended next action.
This is the central design choice. Handover content is useful context, but the current repository is the source of truth.
4. Portable Baseline, Hook Adapters
install updates AGENTS.md and/or CLAUDE.md with a startup snippet. That is the portable baseline because it works across agents that understand repository instructions.
For hook-capable environments, the skill also ships a small SessionStart helper and installer:
node skills/handover/scripts/handover-session-start.js
node skills/handover/scripts/install-handover-hooks.jsThe installer writes Claude Code hook config to .claude/settings.json and Codex hook config to .codex/hooks.json. With no flags it installs both adapters; --claude or --codex installs only one.
The hook deliberately emits only a short startup context: goal, next action, and stop conditions. It reads hook input cwd when provided, works for both Claude Code and Codex SessionStart, and does not inject the full handover body into every new session.
Why Not Inject the Full Handover Automatically?
Full automatic injection sounds convenient, but it can pollute context. Old constraints, solved issues, and stale branch assumptions can become overly influential if they are loaded before verification.
The handover skill keeps startup context small and makes detailed recovery explicit through handover boot. That creates a healthier rhythm: discover that a handover exists, verify it against the current repository, then continue only when the next action is safe.
The handover skill is not a mechanism for blindly trusting previous notes. It is a mechanism for reading previous context, checking it against the current repository, and continuing only with verified next steps.
FAQ
Q. How is handover different from memory?
A. Memory is useful for durable preferences and long-lived knowledge. Handover is short-lived, repository-local work state that must be checked against branch, HEAD, files, and working tree status before use.
Q. Should handover.md be committed?
A. Usually no. Handovers can include local paths, unfinished reasoning, and sensitive work notes. The default mode is private. Use --shared only when the user explicitly wants team-visible handovers.
Q. Does it work across agents?
A. Yes. The portable layer is AGENTS.md / CLAUDE.md startup guidance plus the SKILL.md workflow. The SessionStart hook adapter can be installed for both Claude Code and Codex.
Q. How is this different from cmux fork or delegate workflows?
A. Forking and delegation move or split active work. Handover leaves a verifiable local recovery record for a future session, even if the original session is gone.
Summary
As AI-agent workflows become longer, the question changes from "can the agent solve this now?" to "can the next agent continue safely later?"
The handover skill answers that with a small architecture: private local handoff files, structured metadata, Git-state verification, startup guidance, and Claude Code / Codex hook adapters that provide only minimal context. At ZenChAIne, we see this as part of a broader shift from one-shot AI assistance to durable agentic workflows.