# Handoff

> Saves the live state of the current conversation to `.yoke/handoff/` so a fresh session resumes where this one stopped, referencing existing artifacts instead of duplicating them. Activates when the user writes "handoff", "hand off", "save the context", "dump the conversation", "compact the conversation", "summarize for the next session", "prepare a handoff doc", "pass this to another agent".

- Skill: `yokeloop/handoff` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yokeloop/handoff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yokeloop/handoff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: yokeloop (https://skillmd.com/u/yokeloop)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yokeloop/handoff

---


# Handoff

Compact this conversation into a document that carries everything the next
session needs to continue it. Judge the result by one question: reading only
this file and the artifacts it links, could a fresh agent pick the work up
without asking what was already agreed?

Capture what lives **only in the chat** — the open tasks, the user's exact
requirements, the alternatives already rejected, the state of the working tree.
Everything already written down elsewhere gets a link, never a retelling.

## Where to save

Write one file to `.yoke/handoff/<YYYYMMDD-HHMMSS>-<slug>.md`.

Resolve the path against the **root checkout**, never the current worktree —
`/do` works inside a worktree and `/merge` deletes it, taking any uncommitted
file with it:

```bash
dirname "$(git rev-parse --path-format=absolute --git-common-dir)"
```

Outside a git repository the root is the working directory; say so in the final
message. Take the timestamp from `date '+%Y%m%d-%H%M%S'` — never invent it.

Derive `<slug>` from the first source that answers: the active `.yoke/ai/<slug>/`
task, the current branch name, or a kebab-case summary of the conversation.

Create `.yoke/handoff/` when it is missing. When `.yoke/` itself was missing,
suggest `/yoke:bootstrap` once the file is written.

## What to write

Open with the goal — what this conversation set out to do — then cover:

- **Tasks** — every task raised, each marked done, in progress, or pending.
- **Requirements** — the user's constraints and prohibitions, quoted verbatim.
  A paraphrase loses exactly the wording the next agent then violates.
- **State** — what is done, what is left, and the next step.
- **Decisions** — what was settled and why.
- **Rejected** — the alternatives considered and the reason each was dropped,
  so nobody relitigates them.
- **Git** — branch, worktree, uncommitted files, open PR.
- **Gotchas** — blockers, traps, and anything that cost time to learn.
- **Artifacts** — paths and URLs. Yoke artifacts live under `.yoke/`:
  `.yoke/ai/<slug>/`, `.yoke/adr/`, `.yoke/context.md`, `.yoke/journal.md`.
- **Suggested skills** — which yoke skills the next agent should invoke, given
  where the work sits in the flow (unstarted → `/yoke:do`; implemented but
  unreviewed → `/yoke:review`; PR approved → `/yoke:merge`).

When `.yoke/handoff/` already holds a handoff of this same conversation, link it
as a prior handoff instead of restating it.

Never duplicate a PRD, plan, ADR, issue, commit, or diff — link it.

Redact secrets and PII — API keys, passwords, tokens — as `[REDACTED]`. The file
is committed with the rest of `.yoke/` unless the project ignores it, so a leaked
secret lands in git history.

Treat `$ARGUMENTS` as the focus of the next session and tailor the document to it.

Finish by printing the absolute path, so the user can hand it to the next agent.

## Rules

- Save under `.yoke/handoff/` in the root checkout — never in a worktree, never
  outside `.yoke/`.
- Be exhaustive about what exists only in the conversation; link everything else.
- Quote the user's requirements verbatim.
- Redact secrets and PII.
- Delete nothing: handoffs accumulate.
- Language: match the conversation language, or follow the project-level
  definition in CLAUDE.md / AGENTS.md.