2.9 KiB
2.9 KiB
/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
---
name: handoff
description: Format this session's key context as a copy-pasteable handoff brief for a fresh session or another agent. Use when the user asks for a handoff, wants to carry context over, or is about to /clear, compact or restart.
disable-model-invocation: true
---
# Handoff
Render this session's context as one fenced markdown block, ready to copy
into a fresh session. The reader has the repo but no conversation history,
so write only what the repo does not show: decisions and their reasons,
what was ruled out and why, constraints the user set, what is left.
No chronology, no code, no narrative. Omit empty sections. Mark anything
you are not sure about with `(unverified)`.
```markdown
# Handoff: <task in one line>
## Current state
## Constraints
## Decisions
## Ruled out
## Next step
## Done when
## Notes / tradeoffs
- First draft was 3× longer (rules, per-section explanations, a review
procedure, file-save flow). Simplified after review: `(unverified)`
inline markers replace the separate review-callout procedure, and
everything that was merely obvious or speculative got cut — iterate
by adding lines only after real failures, not upfront.
- `disable-model-invocation: true` keeps it manual — a brief is a session
boundary action, and auto-triggering mid-task would produce noise.
- Output stays in chat by default; saving to a file is outside the skill
(ask for it ad hoc). The brief is disposable. Anything durable belongs
in existing stores: recurring mistake → CLAUDE.md/AGENTS.md, project
decision → project memory/decision log.