Handoff skill

Skill klittle32/handoff-skill

Goal-directed session handoff for AI coding agents (Claude Code, Codex, Pi, Grok). Hand a fresh session exactly what it needs to continue — not a lossy summary. Cross-platform, zero dependencies.

Install

npx -y skills add klittle32/handoff-skill

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Goal-directed session handoff for a fresh agent thread (Amp-style extraction, not lossy compaction). Use when the user runs /handoff, asks to hand off context, start a new session with a focused goal, split work to another thread, or preserve continuity before ending a session. Argument is the goal for the next session — e.g. "/handoff implement phase one of the plan" or "/handoff debug the checkout 400 error".

SKILL.md

5.2 KB, ~1.1k tokens by cl100k_base, as published. Nobody here has run it

handoff

Extract what matters for a new, focused session — do not summarize the whole thread for in-place compaction. The user names the next-session goal; you produce a disposable transfer document plus a copy-paste first message.

This skill is harness-agnostic: it runs the same in Claude Code, Codex, Pi, Grok, or any agent CLI that loads a SKILL.md. It has no external dependencies — no soma, no projection system, nothing beyond file writes and the host agent. Harness-specific details (where to write, sibling tools, policy) live in optional overlay files under references/.

When to use (vs other tools)

Described by function — exact command names vary by harness (see your overlay).

Function	Use when	This skill?
handoff	Split to a new session with a specific goal; keep current thread clean	✅ yes
in-place compaction (often `/compact`)	Stay in the same thread; recover context-window headroom	no
branch/fork the thread	Continue with a copy of full conversation history	no
durable memory write	Save long-term lessons, not session transfer	no

If the user wants a new focused thread, this is the right tool. If they want to keep working in place, point them at their harness's compaction command instead.

Harness overlays

Before choosing a write destination or naming sibling tools, read your harness's overlay if it exists. If you cannot tell which harness you are in, use the portable default in references/destinations.md.

If you are running in	Read overlay	Detect via
Claude Code	`references/claude-code.md`	you are Claude Code; `~/.claude/` exists
Codex CLI	`references/codex.md`	`CODEX_HOME` env or `~/.codex/` exists
Pi	`references/pi.md`	`PI_CODING_AGENT_DIR` env or `~/.pi/` exists
Grok	`references/grok.md`	`~/.grok/` exists
anything else	none — use `references/destinations.md`	portable default

Overlays are additive and optional. The skill is fully functional with none of them: it falls back to the OS temp directory and emits a generic first message.

Workflow

Start with workflows/Handoff.md for the full step list. Summary:

Parse the goal — User arguments (or a short clarifying question) define what the next session will do. Everything else is out of scope for the handoff doc. (Argument passing varies by harness — see references/destinations.md; never rely on $ARGUMENTS-style substitution, which only some harnesses support.)
Gather — Decisions, blockers, COMPLETED / IN PROGRESS / NEXT, artifact paths (plans, reports, open PRs), relevant files to read (with order), failed approaches worth avoiding.
Do not duplicate — Point at existing artifacts by path or URL. Never paste large plan bodies or other content recoverable from a named artifact.
Redact — No API keys, passwords, or PII.
Suggested skills — List skills the receiver should invoke first, with one line each on why. Prefer skills you can confirm exist in the receiving harness (see your overlay).
Write — Use references/template.md structure. Pick destination per your harness overlay, or the OS temp default in references/destinations.md.
Deliver — Print the absolute path to the handoff file and the Suggested first message block (copy-paste ready). Tell the user to start a new session and paste it.

Receiver contract

When continuing from a handoff file: read the FULL file before acting. Do not skim. Artifacts referenced in the doc are authoritative; the handoff is the map, not the source of truth for their contents.

Quality bar

Forward-looking: optimized for what the next agent will do, not a transcript of what happened.
Specific next step: concrete action, not "continue working."
Honest blockers: if stuck, say why.
Disposable: handoff files are working documents, not permanent repo docs (unless the user explicitly asks to keep one in the workspace).
Portable: no harness-specific command names in the body of the handoff doc unless you confirmed the receiver runs that harness.

Verification (optional)

Regression scripts live in scripts/. They resolve paths relative to this skill directory and require no external install:

scripts/verify-handoff-skill.py — structural checks (skill files present, frontmatter contract, template/workflow contract)
scripts/verify-handoff-output.py <handoff.md> — behavioral check that a produced handoff matches references/template.md

Run after editing this skill or validating /handoff output. Use whichever Python launcher you have:

python3 scripts/verify-handoff-skill.py      # or: uv run python scripts/verify-handoff-skill.py

What ships with it: 13 files

43.4 KB alongside SKILL.md, 4 of them executable

Gives 1 of the 12 instructions most agent orchestration skills give in ~1.1k tokens

Counted across 742 of the 995 authors here whose files we hold, read 2026-08-07

Reference existing artifacts by path or URLhere, and in 53 of 742, across 25 files
Run the full test suite after integrating changesin 51 of 742, across 19 files
Dispatch one agent per independent problem domainin 50 of 742, across 17 files
Verify fixes do not conflictin 45 of 742, across 13 files
Include a suggested skills section in the documentin 45 of 742, across 17 files
Redact sensitive informationin 41 of 742, across 11 files
Save to the temporary directory of the operating systemin 39 of 742, across 10 files
Tailor the document to user-provided focus argumentsin 39 of 742, across 9 files
Spot check agent changes for systematic errorsin 34 of 742, across 7 files
Write a handoff document summarising the current conversationin 31 of 742, across 6 files
Assign each agent a specific scopein 23 of 742, across 8 files
Provide specific scope and clear goalin 23 of 742, across 5 files

Said here and by no other author read

read the full workflow file before starting
parse the next-session goal from user arguments
gather decisions blockers status artifact paths
list skills the receiver should invoke first
use the reference template file structure
pick the write destination per harness overlay

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.