nanobot: 2026-09-10 12:45:36

projects/ai/artifacts/handoff-skill.md

@@ -0,0 +1,120 @@
+# /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.