# /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`. Optionally pass the target filename as an argument
(e.g. `/handoff HANDOFF.md`); default is `HANDOFF.md` in the repo root.

## 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. Side-effect: writes
  a file. 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. Ask the user for the output path if not given; default HANDOFF.md in
   the repo root.
2. Draft the brief per the structure above.
3. Show the draft to the user for review. Explicitly point out anything
   you were unsure about (rule 5) so the review is fast.
4. On approval, write the file and confirm the path. Suggest a fresh
   session prompt: "Read <path>. 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.
- 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.