Handoff
Compact the current conversation so a fresh agent can continue without replaying
the session. Reference existing artifacts — never paste their content.
When to use
- Ending a session with unfinished work
- Task mentions "handoff", "交接", "continue later", "next session"
- Context is too large and you need to preserve current state
Structured format
Every handoff uses these exact headings, in this order:
## Goal
## Constraints & Preferences
## Progress (Done / In Progress / Blocked)
## Key Decisions
## Next Steps
## Critical Context
## Suggested Skills (optional)
Fill each with short bullets, not prose. Leave a section empty (with a single
—) rather than padding it. Omit the optional Suggested Skills heading entirely
when no skills apply.
What to include
- Goal: the end state this session was driving toward
- Progress: what's done / in progress / blocked — paths to artifacts, not content
- Key Decisions: trade-offs made, alternatives rejected, and why
- Next Steps: the concrete first actions for the next session
- Critical Context: gotchas, constraints, or facts the next agent must know
- Artifact references: paths/URLs to specs, plans, diffs, issues — never inline
What NOT to include
- Full files or large code blocks — reference paths
- Secrets (API keys, passwords, tokens, PII) — redact with
<REDACTED>
- Content already captured in artifacts — the path is enough
- Session chatter irrelevant to the next agent's work
Output
Save to the OS temp directory:
| Platform |
Path |
| Windows |
$env:TEMP\opencode-handoff-YYYY-MM-DD-HHmm.md |
| Unix |
$TMPDIR/opencode-handoff-YYYY-MM-DD-HHmm.md |
Agent workflow
- Collect paths of existing artifacts (specs, plans, PRs, diffs)
- Fill the structured headings with short bullets: goal, progress, decisions, next steps, critical context
- Add an optional Suggested Skills section listing skills the next session should load (omit if none)
- Write to the OS temp directory, report the path to the user
The handoff is a signpost, not a replay. Keep it under 100 lines.
1---2name: handoff3description: Compact the current conversation into a handoff document for the next agent session. Use when handing off work, ending a long session, or the task mentions "handoff", "交接", "hand over", "continue in next session". References artifacts by path — never copies.4---56# Handoff78Compact the current conversation so a fresh agent can continue without replaying9the session. Reference existing artifacts — never paste their content.1011## When to use1213- Ending a session with unfinished work14- Task mentions "handoff", "交接", "continue later", "next session"15- Context is too large and you need to preserve current state1617## Structured format1819Every handoff uses these exact headings, in this order:2021```22## Goal23## Constraints & Preferences24## Progress (Done / In Progress / Blocked)25## Key Decisions26## Next Steps27## Critical Context28## Suggested Skills (optional)29```3031Fill each with short bullets, not prose. Leave a section empty (with a single32`—`) rather than padding it. Omit the optional Suggested Skills heading entirely33when no skills apply.3435## What to include3637- **Goal**: the end state this session was driving toward38- **Progress**: what's done / in progress / blocked — paths to artifacts, not content39- **Key Decisions**: trade-offs made, alternatives rejected, and why40- **Next Steps**: the concrete first actions for the next session41- **Critical Context**: gotchas, constraints, or facts the next agent must know42- **Artifact references**: paths/URLs to specs, plans, diffs, issues — never inline4344## What NOT to include4546- Full files or large code blocks — reference paths47- Secrets (API keys, passwords, tokens, PII) — redact with `<REDACTED>`48- Content already captured in artifacts — the path is enough49- Session chatter irrelevant to the next agent's work5051## Output5253Save to the OS temp directory:5455| Platform | Path |56|----------|------|57| Windows | `$env:TEMP\opencode-handoff-YYYY-MM-DD-HHmm.md` |58| Unix | `$TMPDIR/opencode-handoff-YYYY-MM-DD-HHmm.md` |5960## Agent workflow61621. Collect paths of existing artifacts (specs, plans, PRs, diffs)632. Fill the structured headings with short bullets: goal, progress, decisions, next steps, critical context643. Add an optional **Suggested Skills** section listing skills the next session should load (omit if none)654. Write to the OS temp directory, report the path to the user6667The handoff is a signpost, not a replay. Keep it under 100 lines.
znlgis