| name | handoff |
| description | Compact the current conversation into a handoff document so another agent can continue the work. Use when ending a coding session, switching tasks, when the context window is getting full, or before handing off to a teammate or another AI agent. Saves to OS temp directory, not the workspace. |
| argument-hint | [what the next session will focus on] |
Session Handoff
"Every session ends. Make the next one count."
Philosophy
Sessions end. Context is lost. Hours of progress disappear. This skill prevents that by compressing the session into a document a fresh agent can use to continue immediately.
Workflow
Step 1: Capture Current State
- What was accomplished? One-line per completed task.
- What's in progress? What's done, what's remaining, any blockers.
- What was decided? Key decisions with rationale. This prevents re-litigating in the next session.
Step 2: Capture Technical Context
- Files changed — Each modified file with brief description
- Codebase state — Do tests pass? Deployable? Any temporary hacks?
- Domain knowledge gained — Insights about codebase, business logic, architecture
Step 3: Capture Next Steps
- Immediate — Must do next
- Soon — Should do soon
- Later — Nice to have
Step 4: Write the Document
# Handoff: [Session Focus]
## Completed
- [Task 1]: [summary]
- [Task 2]: [summary]
## In Progress
- [Task 3]: Done — [what's done]. Remaining — [what's left]. Blocker — [if any].
## Decisions
- [Decision 1]: [what] — Rationale: [why]
- [Decision 2]: [what] — Rationale: [why]
## Files Changed
- `path/to/file1.ts`: [description]
- `path/to/file2.ts`: [description]
## Codebase State
- Tests: [all pass / X failing — reason]
- Deployable: [yes / no — reason]
- TODOs: [temporary hacks]
## Domain Knowledge
- [Insight 1]
- [Insight 2]
## Next Steps
1. **Immediate:** [must do]
2. **Soon:** [should do]
3. **Later:** [nice to have]
## Open Questions
- [Question 1]
## Suggested Skills
- `/grill` — [why]
- `/tdd` — [why]
Step 5: Save
Save to OS temp directory (not workspace). Redact sensitive info (API keys, passwords, PII). Do not duplicate content already in PRDs, ADRs, issues, commits — reference them by path or URL.
Anti-Patterns
- Writing a novel — Use
/caveman style if needed
- Omitting decisions — Future sessions WILL re-litigate without rationale
- Vague next steps — "Continue working on the feature" is not actionable
- Forgetting test state — Next session needs to know immediately
Integration
- Use
/caveman to keep the handoff compact
- Use
/to-issues to convert next steps into grabbable issues
- Next session should start with
/grill to re-align
