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:
- 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.
- Details — policies, conventions, data structures, schemas, API
contracts, environment specifics. Everything the next agent must hold as
ground truth while working.
- Suggested skills — a named section listing the skills the next agent
should invoke, each with one line on when/why.
- 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.
1---2name: handoff3description: 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.4---56# Handoff78Write a handoff document summarising the current conversation so a fresh9agent can continue the work with zero access to this session's context.1011The next agent knows **nothing**: not the codenames you invented mid-session,12not which files you touched, not why a decision was made. Write for that13reader.1415## Output contract1617Produce **one markdown document**. It has exactly these parts, in this order:18191. **Project overview** — open with the project's purpose, background,20 resources, and a plain description. List the tools in play (CLIs, MCP21 servers, scripts, services) and *how to use each one* — commands,22 entry points, and any non-obvious invocation details.232. **Details** — policies, conventions, data structures, schemas, API24 contracts, environment specifics. Everything the next agent must hold as25 ground truth while working.263. **Suggested skills** — a named section listing the skills the next agent27 should invoke, each with one line on when/why.284. **Current state → open issues → what to do next** — the document ends29 with these three, in this order. State what is done and verified, what is30 unresolved or blocked, and the concrete next steps.3132Close the document with an explicit instruction to the next agent: *remember33this information and wait for further instructions — do not start working on34anything.* The handoff transfers state, it does not assign work.3536## Rules3738- **Language:** write the document in the primary language of the current39 chat (Hebrew chat → Hebrew document; code identifiers, commands, and paths40 stay as-is).41- **No duplication:** content already captured in other artifacts — specs,42 plans, ADRs, issues, commits, diffs — is referenced by path or URL, never43 restated. The handoff carries only what lives nowhere else.44- **Redaction:** redact API keys, tokens, passwords, connection strings, and45 personally identifiable information. Keep credential *names* (`STRIPE_KEY`)46 so the next agent knows what to load; never the values.47- **Arguments:** if the user passed arguments, treat them as a description of48 what the next session will focus on and weight the document accordingly —49 expand the sections that session needs, compress the rest.5051## Delivery5253- **CLI / IDE sessions:** save the file to the OS temporary directory (or the54 session scratchpad) — *not* the current workspace — and give the user the55 full path.56- **Chat UIs with downloads/artifacts:** deliver the markdown so it is57 downloadable from within the chat body (artifact or file attachment), and58 also state where it was saved if a filesystem exists.5960## Skeleton6162```markdown63# Handoff — <project / task name> (<date>)6465## Project overview66<purpose, background, resources, description>6768### Tools69- <tool> — <how to use: command / endpoint / auth env-var name>7071## Details72<policies, data structures, schemas, conventions>7374## Suggested skills75- <skill-name> — <when/why to invoke>7677## Current state78## Open issues79## What to do next8081---82*To the next agent: remember this information and wait for further83instructions. Do not start working on anything yet.*84```8586## Auto-trigger at high context usage8788A skill cannot watch the context window by itself — triggering above a89usage threshold is done with a hook that measures the transcript and injects90a reminder to invoke this skill. See [REFERENCE.md](REFERENCE.md) for the91ready-made hook script and installation.
digitizers