77 lines
2.9 KiB
Markdown
77 lines
2.9 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: 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. |