handoff

name	handoff
description	Use when the current session's work must continue in a fresh agent session — the context window is nearly full or about to be compacted, the user is ending a work session and will resume later, the work is being handed to another agent, machine, or teammate, or the user asks for a "handoff", "handoff document", "session summary to continue from", or to "prepare this for the next session". Also fires when a hook or system reminder reports high context usage and asks for a handoff. Not for writing project documentation for humans (README, docs, changelogs, reports) — only for transferring this session's state to a future agent session.
argument-hint	What will the next session focus on?

Handoff

Write a handoff document summarising the current conversation so a fresh agent can continue the work with zero access to this session's context.

The next agent knows nothing: not the codenames you invented mid-session, not which files you touched, not why a decision was made. Write for that reader.

Output contract

Produce one markdown document. It has exactly these parts, in this order:

1. Project overview — open with the project's purpose, background, resources, and a plain description. List the tools in play (CLIs, MCP servers, scripts, services) and how to use each one — commands, entry points, and any non-obvious invocation details.
2. Details — policies, conventions, data structures, schemas, API contracts, environment specifics. Everything the next agent must hold as ground truth while working.
3. Suggested skills — a named section listing the skills the next agent should invoke, each with one line on when/why.
4. Current state → open issues → what to do next — the document ends with these three, in this order. State what is done and verified, what is unresolved or blocked, and the concrete next steps.

Close the document with an explicit instruction to the next agent: remember this information and wait for further instructions — do not start working on anything. The handoff transfers state, it does not assign work.

Rules

• Language: write the document in the primary language of the current chat (Hebrew chat → Hebrew document; code identifiers, commands, and paths stay as-is).
• No duplication: content already captured in other artifacts — specs, plans, ADRs, issues, commits, diffs — is referenced by path or URL, never restated. The handoff carries only what lives nowhere else.
• Redaction: redact API keys, tokens, passwords, connection strings, and personally identifiable information. Keep credential names (STRIPE_KEY) so the next agent knows what to load; never the values.
• Arguments: if the user passed arguments, treat them as a description of what the next session will focus on and weight the document accordingly — expand the sections that session needs, compress the rest.

Delivery

• CLI / IDE sessions: save the file to the OS temporary directory (or the session scratchpad) — not the current workspace — and give the user the full path.
• Chat UIs with downloads/artifacts: deliver the markdown so it is downloadable from within the chat body (artifact or file attachment), and also state where it was saved if a filesystem exists.

Skeleton

# Handoff — <project / task name> (<date>)

## Project overview
<purpose, background, resources, description>

### Tools
- <tool> — <how to use: command / endpoint / auth env-var name>

## Details
<policies, data structures, schemas, conventions>

## Suggested skills
- <skill-name> — <when/why to invoke>

## Current state
## Open issues
## What to do next

---
*To the next agent: remember this information and wait for further
instructions. Do not start working on anything yet.*

Auto-trigger at high context usage

A skill cannot watch the context window by itself — triggering above a usage threshold is done with a hook that measures the transcript and injects a reminder to invoke this skill. See REFERENCE.md for the ready-made hook script and installation.