| name | agent-handoff |
| description | Use when an AI agent must hand off in-progress work to a successor agent and needs a structured, high-signal payload that prevents hallucination, re-litigation of settled decisions, and duplicate work. |
Agent Handoff
Overview
Agent handoff produces a structured state payload that lets a successor agent continue work without rediscovering settled context. The handoff is NOT a conversation dump. It is a compact, schema-driven payload that lists artifacts, decisions, constraints, open questions, a concrete next step, and surgical file anchors.
Core Contract
- Produce a JSON payload following the handoff schema; every section is required.
- List concrete artifacts, not narrative descriptions of process.
- Include decision rationale to prevent the successor from re-litigating settled choices.
- Constraints must be prohibitions ("Do not X"), not advice.
- Provide a single, immediately executable next step — not a plan or list.
- Context anchors must point to specific files and line ranges, not entire directories.
- Be stingy with tokens: if a section is empty, write
[]. Do not duplicate information already encoded in anchors.
When to Use
Use this skill when an agent is about to transfer in-progress work to another agent, either within a team, across a handoff boundary in a multi-agent system, or when saving checkpoints for later resumption.
When Not to Use
Do not use this skill for:
- Simple task completion summaries where the work is done (no successor needed)
- Conversation logs or chat exports that are meant for human review
- Project documentation or architecture decisions records (use project docs instead)
- Same-role resumption after a reset or context-window pressure event — use
context-compaction instead
Workflow
Phase 1 — Prepare the Handoff
Before writing the payload, identify:
- What was actually completed (concrete artifacts)
- What decisions were made and why
- What must NOT be touched (constraints and non-goals)
- What single action the successor should take first
Phase 2 — Produce the Payload
Generate a JSON payload matching the handoff schema. Every section is required. Include all fields even if empty.
Phase 3 — Apply System-Level Filters
If the runtime supports input filters:
- Strip noisy intermediate messages (failed tool calls, retries, debugging chatter)
- Keep only the user's original prompts and the final successful assistant responses
- Pass the cleaned history alongside the structured payload
Phase 4 — Validate
Before declaring the handoff complete, check:
- Every artifact entry names a concrete deliverable
- Every decision includes its reason
- The next step is a single, executable instruction
- Context anchors reference real files with line ranges
- Constraints are prohibitions, not vague warnings
- No narrative or meta-commentary has leaked into the payload
References
- Handoff Schema — Full JSON schema with field descriptions and examples
Failure Modes
- Producing narrative ("I tried several approaches") instead of artifacts ("Created src/auth.py")
- Omitting decision reasons, forcing the successor to guess why a choice was made
- Writing vague constraints like "Be careful" instead of "Do not modify migrations/"
- Providing a multi-step plan as the next step instead of one concrete action
- Including entire file contents or full directory paths as context anchors instead of surgical line ranges
- Passing unfiltered conversation history full of failed attempts and intermediate noise
Final Checklist
