Agent Handoff

Never ask "how do I run this?" again. A universal skill for AI coding agents to write and use project handover documents.

English | 中文

When an AI agent finishes work on a project (or hands off to another agent), it writes a timestamped handoff document under .handoff/ (e.g., .handoff/2026-05-11.md), with HANDOFF.md as a symlink pointing to the latest entry. The next person can pick up instantly — startup commands, env vars, directory structure, known issues, TODOs, and more. No follow-up questions needed.

Supported Agents

Agent	Format	Installation Path
Claude Code	SKILL.md	.claude/skills/handoff/
OpenCode	SKILL.md	.opencode/skills/handoff/
Codex (OpenAI)	SKILL.md	~/.codex/skills/handoff/
Gemini CLI	SKILL.md	.gemini/skills/handoff/
Cursor	.mdc rule	.cursor/rules/handoff.mdc

AI Agent Auto-Install Guide

For AI agents: If a user asks you to set up this skill, follow the steps for their platform below. No user interaction needed.

Auto-Detect the Platform

Check these paths to determine the agent platform:

Platform	Detection Keyword	Skills Directory
Claude Code	.claude/ exists	.claude/skills/handoff/
OpenCode	.opencode/ exists	.opencode/skills/handoff/
Codex (OpenAI)	codex in CLI	~/.codex/skills/handoff/
Gemini CLI	gemini in CLI	.gemini/skills/handoff/
Cursor	.cursor/ exists	.cursor/rules/handoff.mdc

Installation Commands (for AI agents to execute)

# === Claude Code / OpenCode / Codex / Gemini CLI ===
git clone https://github.com/xiaomaimuchanyiyiba/agent-handoff.git /tmp/agent-handoff

# For Claude Code:
mkdir -p .claude/skills/handoff && cp /tmp/agent-handoff/SKILL.md /tmp/agent-handoff/LICENSE .claude/skills/handoff/

# For OpenCode:
mkdir -p .opencode/skills/handoff && cp /tmp/agent-handoff/SKILL.md /tmp/agent-handoff/LICENSE .opencode/skills/handoff/

# For Codex:
mkdir -p ~/.codex/skills/handoff && cp /tmp/agent-handoff/SKILL.md /tmp/agent-handoff/LICENSE ~/.codex/skills/handoff/

# For Gemini CLI:
mkdir -p .gemini/skills/handoff && cp /tmp/agent-handoff/SKILL.md /tmp/agent-handoff/LICENSE .gemini/skills/handoff/

# === Cursor ===
mkdir -p .cursor/rules && cp /tmp/agent-handoff/cursor/rules/handoff.mdc .cursor/rules/

Verify Installation

# Check the skill file exists with frontmatter
head -4 .claude/skills/handoff/SKILL.md 2>/dev/null || \
head -4 .opencode/skills/handoff/SKILL.md 2>/dev/null || \
head -4 ~/.codex/skills/handoff/SKILL.md 2>/dev/null || \
echo "Skill not found in known paths"

Expected output should include name: handoff in the YAML frontmatter.

---

Manual Quick Start

Claude Code / OpenCode / Codex / Gemini CLI

git clone https://github.com/xiaomaimuchanyiyiba/agent-handoff.git /tmp/agent-handoff
# Project-level (recommended — only the current project can use it)
cp -r /tmp/agent-handoff .claude/skills/handoff
# For OpenCode:
cp -r /tmp/agent-handoff .opencode/skills/handoff

Cursor

cp /tmp/agent-handoff/cursor/rules/handoff.mdc .cursor/rules/handoff.mdc

---

Usage

Triggering the Skill

The skill auto-detects context. Use any of these phrases:

Wave mode (handing off work):

• "I'm done with this feature, write a handoff"
• "Document this project for the next person"
• "Create a handoff for this module"
• "I need to archive this project"

Land mode (taking over work):

• "Take over this project"
• "Land on this codebase"
• "Read the handoff and get me up to speed"
• "What's the status of this project?"

Using with Cursor

In Cursor, mention the rule explicitly or let the agent auto-detect. Trigger with:

@handoff write a handoff
@handoff take over this project

What Gets Generated

The agent writes timestamped handoff documents under .handoff/ at project root, with HANDOFF.md as a symlink to the latest:

.handoff/
├── 2026-05-11.md         # timestamped entries
├── 2026-05-11.001.md     # multiple entries same day
└── 2026-05-10.md
HANDOFF.md -> .handoff/2026-05-11.md   # symlink to latest

Each document covers:

1. Project Overview — what this project does
2. Startup Commands — exact commands to get running
3. Environment Variables — names and descriptions (values redacted)
4. Key Directory Structure — annotated directory tree
5. Current Status — build/test/lint results, known issues
6. Next Steps — prioritized TODO list (high / medium / low)

For projects with databases, APIs, frontends, or multi-agent systems, additional sections are added automatically.

How It Works

Two modes, auto-detected:

Mode	When	What Happens
🌊 Wave	Leaving a project	Creates timestamped file in .handoff/, updates HANDOFF.md symlink, with startup, status, TODOs
🛬 Land	Taking over a project	Reads latest .handoff/ entry, analyzes risks, executes TODOs

If a .handoff/ directory already exists but might be stale, the agent asks before acting.

Wave Mode Output

The agent writes a structured handoff doc under .handoff/ covering:

• Core sections (always included): project overview, startup commands, env vars, directory structure, current status, next steps
• Supplementary sections (added as needed): database schema, API endpoints, frontend routes, agent architecture, async tasks, known deviations, design docs

Land Mode Output

## Handoff Analysis: my-project

### Key Findings
- 3 deviations from design spec detected
- 2 of 5 submodules partially implemented

### TODO Priorities
🔴 Urgent: fix auth middleware (blocking deploy)
🟡 Soon: add rate limiting
🟢 Backlog: migrate to new API version

Philosophy

• No guessing: uncertainties are marked ⚠️ TBD, never fabricated
• No sugarcoating: problems and deviations recorded honestly
• Analyze before acting: in Land mode, findings are presented for confirmation first
• Keep the trail: each update creates a new timestamped file — history is never overwritten

Contributing

PRs welcome — especially for additional agent platform support.

License

MIT — see LICENSE.