oh-my-skills/skills/session-handoff/SKILL.md

---

name: "session-handoff"

description: "Write an on-demand HANDOFF.md summary, requested by the user, to hand the work off to another agent or a new session, at any point during the work. Always asks the user (via ask_user_question) which highlights to export before writing the file."

When to Use

When the user explicitly requests it (e.g. "prepare a handoff", "write the handoff") or states that the work will continue with another agent (new pi session, subagent, external agent). Not tied to the end of a session or task: it can be used at any point during the work, even midway through a task in progress.

Procedure

1. Confirm the purpose of the handoff: what the next agent will have to do and which state is needed to resume. If invoked mid-work, clarify the scope with the user: the handoff covers the work done so far, not necessarily a closed task.
2. List the candidate highlights that emerged from the session (completed work, decisions, files touched, open problems, next steps) and ask which ones to export in the handoff using ask_user_question: a structured multiSelect question with the candidate points as options (max 4 options per question; if there are more candidates, group them or use multiple questions). Proceed to writing only after the user's answer.
3. Write HANDOFF.md in the project root with a fixed structure: Objective, Status (done/in progress), Decisions made, Files modified/created, Verification, Open problems, Next steps, Useful commands. Include only the points confirmed by the user; if a section has no selected content, write it empty with a "not applicable" note.
4. For each file mentioned, report only path + reason for the change, not the content. Use pointers (paths, commands, commits) instead of raw content.
5. In the Verification section, report the commands already executed with their outcome (test/build/lint) and any known errors or open risks. If the work is in progress, explicitly mark what has not yet been verified.
6. Handoff to the other agent: new pi session → pi -p "@HANDOFF.md Continue from here: ..."; subagent → pass the file path as an instruction; external agent → copy-paste the markdown (the file is self-contained).
7. If the session continues beyond the handoff point, update the file instead of creating a second one.
8. To make it repeatable, reuse this same template in every subsequent handoff.

Pitfalls

• Do not write the handoff without first asking the user for and obtaining the list of highlights to export.
• Do not collect the highlight selection as free text when ask_user_question is available: the structured question makes the selection explicit and traceable.
• Do not export the entire transcript: the value is the summary, not the log.
• Do not omit verification status and open risks: they are what the next agent really needs.
• If the handoff is generated mid-work, do not present the status as complete: clearly mark what is halfway done or unverified.
• Avoid vague summaries like 'Done' or 'Ok': state concrete outcomes and the commands executed.
• Do not leave the file without a Next steps section: it must be executable by an agent starting from zero.
• Pay attention to the HANDOFF.md format if the target agent is external (e.g. no pi-specific syntax).

Verification

1. Before writing, the highlight selection was requested from the user via ask_user_question and the file reflects the selection received.
2. HANDOFF.md exists in the project root and contains all the expected sections.
3. A new agent can resume by reading only the file: the next steps are actionable and the referenced commands exist.
4. The file paths mentioned in the handoff are real (verify with ls/read).