Skip to content
Development
Skill

/handoff

Write a handoff file at .turbo/handoff/ capturing session state so a fresh session can continue. Use when the user asks to \"create a handoff\", \"save session state\", or \"handoff before compact\".

From plugin
turbo
42074 skills

Claude Code

$ npx -y skills add tobihagemann/turbo --skill handoff --agent claude-code

SKILL.md

handoff.SKILL.md
name: handoff
description: "Write a handoff file at .turbo/handoff/ capturing session state so a fresh session can continue. Use when the user asks to \"create a handoff\", \"save session state\", or \"handoff before compact\"."

Handoff

Write a session handoff file at `.turbo/handoff/<YYYY-MM-DD>-<slug>.md` so a fresh session can pick up where this one left off.

Step 1: Resolve the Target Path

Get today's date: `date +%Y-%m-%d`.

Pick a slug for the current task:

  • Lowercase
  • Replace non-alphanumeric characters with hyphens
  • Collapse consecutive hyphens
  • Trim leading and trailing hyphens
  • Truncate to 40 characters at a word boundary

If the work is anchored to an existing plan at `.turbo/plans/<slug>.md`, reuse that plan's slug verbatim.

The user may pass an explicit slug or output path; honor it.

Resolve the repo root with `git rev-parse --show-toplevel`, except inside a linked worktree — where `git rev-parse --git-dir` differs from `--git-common-dir` — in which case use the parent of the common dir, so the handoff lands in the main checkout rather than in a worktree that is destroyed with its branch.

The target path is `.turbo/handoff/<YYYY-MM-DD>-<slug>.md` under that root. A generated slug takes `-2`, `-3`, and so on until the path is free. When the user supplied the slug or path and it already exists, use `AskUserQuestion` to offer overwrite, a numeric suffix, or a different slug.

When an open decision will outlive the rest of the session's state, still unresolved while the work around it is finished, give it its own handoff. Everything else stays in a single file. Slug the split handoff for that decision rather than appending a collision suffix, and write it to stand alone.

State the chosen path before continuing.

Step 2: Gather Session State

Run `git status --short` to see uncommitted changes in the working tree.

Survey the conversation context for:

  • **Current task**: what is being worked on, in one or two sentences
  • **Workflow status**: where in the workflow this session is (drafting, refining iteration N, applying findings, implementing step M of K, investigating, blocked on Q, etc.)
  • **Active artifact**: path to the plan or other file at the center of the work, if one exists
  • **Open decisions**: questions raised but not resolved, choices the user is still weighing, escalations awaiting input, actions only the user can take
  • **In-flight changes**: staged or unstaged edits that are not yet committed; what each change is doing and what is missing
  • **Closed avenues**: approaches that were built or tested and then abandoned, with the observed evidence that ruled them out
  • **Next step**: the first concrete action the new session should take. When the user has stated what they want to work on next, that intent leads and any work left in flight is ordered after it; say so in the same statement when that work should not resume at all

Call the `mcp__turbo__open-items` tool with `action` set to `list`, and carry each item's text and detail, without its id, into the open decisions, merging any the survey already found.

Read the backlog under the repo root resolved in Step 1: `.turbo/backlog.md`, and the legacy `.turbo/improvements.md` when one exists. Note any entry this handoff takes over. When no entry clearly matches, leave the backlog alone.

When something is genuinely unclear and would leave a gap in the handoff, use `AskUserQuestion` to resolve it. Default to inferring quietly when the conversation makes the answer clear.

Step 3: Write the Handoff File

Write the file at the path picked in Step 1 with the Write tool, which creates `.turbo/handoff/` if it does not exist, including when that path is in the main checkout outside the current working directory: the Bash sandbox denies a shell write there.

When that write is refused while this session runs inside a linked worktree, report that the handoff cannot be persisted from here and print it in full so it can be pasted in from a session that can write to the main checkout, naming any backlog entry noted in Step 2 for deletion there. Leave it out of the worktree's own `.turbo/`, which is gitignored and is destroyed with the worktree.

Lead with `# Handoff: <Task Title>`. Cover the items gathered in Step 2 in whatever structure fits the session — drafting, refining, implementing, and investigating sessions each have different shapes and don't all map to the same headings. Close with a clear statement of the next concrete action so the new session knows exactly what to do first.

Keep it dense. Omit anything that has no real content. Point to content a plan, issue, commit, or diff already holds by path, URL, or hash rather than restating it. Carry content that lives only in a linked worktree's uncommitted changes or gitignored files into the handoff itself.

Write `<REDACTED>` in place of any secret the session handled, such as an API key, token, or password.

When this handoff splits an open decision out of an existing one, add a line to that existing handoff pointing at the new path, and remove the content the new file now carries.

Step 4: Confirm

Once the handoff file exists, delete each backlog entry noted in Step 2 from the file that holds it. Delete a backlog file left with no entries.

Tell the user where the handoff was written, name any backlog entry deleted and any existing handoff edited to point at a split, and quote the next-step statement so the path forward is visible at a glance.

Then use the TaskList tool and proceed to any remaining task.

Read more
@tobihagemann
Ships withturbo

A human-gated agentic software factory for Claude Code and Codex: you decide what to build and judge the result; skills shape, build, polish, ship, and learn.

Stars on GitHub

Momentum

stars in total
420
Star history of tobihagemann/turbo on GitHub, a chart by star-history.com

Other skills on turbo.

apply-turbo-handoffs

apply-turbo-handoffs

Audit the turbo lessons /self-improve wrote to .turbo/handoff/ and apply approved ones. Use when the user asks to \"read…

@tobihagemann@tobihagemannInstall Skill
apply-findings

apply-findings

Apply accepted review findings as code changes, escalating ambiguous ones to the user. Use when the user asks to \"apply…

@tobihagemann@tobihagemannInstall Skill
assess-technical-debt

assess-technical-debt

Assess project-wide technical debt (hotspots, deprecated APIs, duplication, low-value tests) into a ranked report. Use when the…

@tobihagemann@tobihagemannInstall Skill
backlog

backlog

Capture an out-of-scope improvement or accepted simplification in .turbo/backlog.md. Use proactively mid-task, or when the user…

@tobihagemann@tobihagemannInstall Skill
code-style

code-style

Enforce existence, reuse, mirror, and symmetry principles so new code stays minimal and consistent. Use when writing, changing,…

@tobihagemann@tobihagemannInstall Skill

More skills from other plugins.

brainstorming
Auto-invoked

brainstorming

You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or…

@obra@obraInstall Skill
ask-matt

ask-matt

Ask which skill or flow fits your situation. A router over the skills in this repo.

skills2w309k
@mattpocock@mattpocockInstall Skill
accessibility
Auto-invoked

accessibility

Design, implement, and audit accessible UI to WCAG 2.2 Level AA across Web, iOS, and Android — semantic ARIA roles and labels,…

ecc2w293k
@affaan-m@affaan-mInstall Skill
compiler-commit

compiler-commit

Use when you want to verify compiler changes and commit with the correct convention. Runs tests, lint, and format, then commits…

react6d252k
@facebook@facebookInstall Skill

Questions about handoff.

Which coding agents can use handoff?
handoff installs in Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode and Windsurf with the skills CLI, using each agent's flag shown on this page. Flowy's auto-invocation, which fires a skill when your prompt matches, runs in Claude Code only.