126 lines
4.8 KiB
Markdown
126 lines
4.8 KiB
Markdown
# /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. |