# /handoff skill for Claude Code

## My take

Good idea. Rationale:

- The handoff brief is the cheapest reliable carrier of context between
  sessions, but it is written at the exact moment nobody wants to write it:
  at a session boundary, from a bloated context, by hand.
- A skill turns it into one word: `/handoff`. The effort argument against
  "transfer via artifacts" disappears.
- Skills follow the Agent Skills open standard (agentskills.io), so the same
  SKILL.md works in Codex and other tools with a compatible loader.
- One important design decision: the brief must be written **for the next
  agent as the reader**, not as a human retrospective. That changes the
  content: no narrative, no chronology — just state, decisions, and
  constraints, in an order optimized for cold-context consumption.

## Installation

Pick a location by scope:

| Scope | Path |
|---|---|
| Personal (all your projects) | `~/.claude/skills/handoff/SKILL.md` |
| One repo (shareable, commit it) | `<repo>/.claude/skills/handoff/SKILL.md` |

(`.claude/commands/handoff.md` is the older format and still works, but
skills are preferred for new work.)

Invoke with `/handoff`. The brief is rendered in the chat as a markdown
block, ready to copy-paste. If you ask for a file, it saves to `HANDOFF.md`
in the repo root (or a path you give).

## SKILL.md content

```markdown
---
name: handoff
description: >
  Write a handoff brief that lets a fresh session (or a different agent)
  continue this work without this session's conversation history. Run
  manually when wrapping up a task or before /clear. Output is a markdown
  block in the chat, ready to copy-paste; writes a file only if the user
  asks. Not for use mid-task.
disable-model-invocation: true
---

# Handoff

Write a brief that transfers this session's working context to another AI
agent that starts with ZERO conversation history. The reader will have the
repo and this file — nothing else.

## Rules

1. **Do not duplicate the repo.** The reader can read code, diffs, and file
   trees. State what exists only where it matters (file paths as entry
   points), never paste code or file contents.
2. **Write what is NOT visible in the repo**: decisions and their reasons,
   rejected approaches and their reasons, constraints from the user,
   open questions. If a decision is recorded in a committed doc, reference
   the doc in one line instead of restating it.
3. **No chronology, no narrative, no reflection.** State facts for a cold
   reader. "We tried X then Y" is wrong; "X and Y are ruled out (reason)"
   is right.
4. **Be specific, not complete.** A brief that lists everything real says
   nothing. Include only what changes the reader's behavior.
5. You are writing from a full (possibly degraded) context. Be conservative:
   if you are not sure something was actually decided, mark it as open,
   do not present it as fact.

## Structure (omit a section if empty; keep this order)

# Handoff: <one-line task description>

## Goal
What this work is for. 1–2 sentences.

## Current state
What is done and verified. Reference files/paths as entry points.
If verification is partial, say exactly which part is unverified.

## Constraints
Hard rules from the user (style, architecture, scope, "do not" rules).

## Decisions
- <decision> — <why>. One bullet per decision.

## Ruled out
- <approach> — <why it failed or was rejected>. This section is the most
  valuable one: it prevents the next agent from re-walking dead ends.

## Next step
The single most useful action for the reader, with enough precision to
start without re-deriving the plan.

## Done when
Verifiable completion condition(s).

## Procedure

1. Draft the brief per the structure above and render it as a single
   fenced markdown block in the chat, ready to copy-paste.
2. Explicitly point out anything you were unsure about (rule 5) so review
   is fast.
3. Only if the user asks, save the brief to a file — default HANDOFF.md
   in the repo root (or the path they give) — and confirm the path.
4. Suggest a fresh session prompt: "Read <path or pasted brief>. Task:
   <goal>. Done when: <done-when>."
```

## Notes / tradeoffs

- `disable-model-invocation: true` keeps it manual — a brief is a session
  boundary action, and auto-triggering mid-task would produce noise.
- Default output is chat, not a file: the brief is disposable, and a file
  that nobody reads later is clutter. File only on explicit request —
  the user decides whether the receiving side reads it via path or paste.
- The 30-second user review stays in the loop on purpose: the model writes
  the brief at its weakest point (full context), so the human is the
  fact-checker, not the writer.
- The brief is disposable. Anything durable belongs in existing stores:
  recurring mistake → CLAUDE.md/AGENTS.md, project decision → project
  memory/decision log. Handoff carries it across the session boundary;
  it is not an archive.