| name | handoff |
| description | Compact the current conversation into a structured handoff document for another agent to pick up where this one left off. Use when the user says "hand off to <name>", "do a handoff", "summarize this session for another agent", or wants to pass work to a different Copilot CLI session. If a recipient is named (e.g., "hand off to juliett"), the skill auto-delivers via the mailbox skill after writing the doc. |
| argument-hint | What will the next session be used for? Optionally include a recipient name (e.g., 'send to juliett about X') to auto-deliver via the mailbox skill. |
Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
For work that spans multiple sessions, persist durable goals and plans to a committed repo doc (e.g. docs/<feature>-plan.md), not just the conversation or session checkpoints — context compaction can otherwise silently narrow the scope. Reference that doc from the handoff.
Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.
Automated delivery to another agent session (optional)
If the user names a recipient session ("send to juliett", "hand this to kilo", "deliver to alpha", etc.) AND the mailbox skill is available, after writing the handoff document automatically dispatch it via mailbox so the recipient agent picks it up without manual file passing:
~/.copilot/skills/mailbox/scripts/mailbox-send.sh <recipient> \
--summary "handoff: <one-line topic>" \
--message "Continuing <topic>. Read the attached handoff doc, then resume." \
--file <path-to-handoff-doc>
The recipient's mailbox skill will surface this on its next /mailbox dispatch (immediate if their tmux session is running, on next ca <recipient> if they're cold). Tell the user: "Handoff sent to — they'll see it on their next turn."
If the user did NOT name a recipient, do not invoke mailbox; just write the doc and report the path so the user can hand it off manually or via /mailbox themselves.
