nanobot-runtime/projects/ai/artifacts/handoff-skill.md

/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: >
  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.