handoff · nicknisi — Claude Code skill: what it does, how to install
Turns a working session into a short handoff file, so a fresh agent can pick up unfinished work without rebuilding the context.
MIT ★ 114 updated 2026-08-11
/plugin marketplace add nicknisi/claude-plugins
/plugin install essentials@nicknisiWhat handoff does
The skill writes down where a session stands and what comes next, aimed at an agent that has seen none of the conversation. The file lands at a mktemp path with .md appended. Compression is the goal; a transcript is not.
Sections cover the goal, the current branch and code state, decisions already settled, approaches that failed, open questions and blockers, prioritised next steps, plus skills worth invoking later. Sections that do not fit are left out. Existing PRDs, plans, ADRs, issues, commits and diffs get referenced by path or URL instead of copied. A code block stays only when it carries context found nowhere else.
Pass a note on what the next session will handle and the whole document leans that way. Skip the argument and you get an even summary of everything. The skill asks for under 200 lines.
What it helps with
- carry unfinished work into a new session without losing context
- record settled decisions and their reasons
- list abandoned approaches so the next session skips them
- start clean once the conversation has grown long
- collect open questions and blockers before a pause
Example prompts for the agent
- Write a handoff document for the next session, another agent takes over from here.
- Save the context as a handoff — the next session starts with the open questions.
- Context is getting long, compact it into a handoff and let's start fresh.
How to install handoff
1Plugin marketplace
/plugin marketplace add nicknisi/claude-plugins/plugin install essentials@nicknisiThis installs the whole essentials plugin with all its skills
2Skills CLI (Vercel)
npx skills add nicknisi/claude-plugins --skill handoff -a claude-code3Manually: put the files in place
~/.claude/skills/handoff/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/handoff/
1Skills CLI (Vercel)
npx skills add nicknisi/claude-plugins --skill handoff -a codex2Manually: put the files in place
.agents/skills/handoff/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add nicknisi/claude-plugins --skill handoff -a cursor2Manually: put the files in place
.cursor/skills/handoff/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install nicknisi/claude-plugins plugins/essentials/skills/handoff2Manually: put the files in place
.github/skills/handoff/SKILL.md1Skills CLI (Vercel)
npx skills add nicknisi/claude-plugins --skill handoff -a gemini-cli2Platform CLI
gemini skills install https://github.com/nicknisi/claude-plugins --path plugins/essentials/skills/handoffManually: put the files in place
.devin/skills/handoff/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about handoff
How do I install handoff in Claude Code?
From the marketplace: run /plugin marketplace add nicknisi/claude-plugins, then /plugin install essentials@nicknisi.
What does handoff do?
It compacts the current session into a document for the next agent: the goal, what is built, decisions taken, dead ends, open questions and next steps.
What should I pass as the argument?
A short description of what the next session will focus on. The document is shaped around it.
Source text
SKILL.md · MIT
---
name: handoff
description: Compact the current conversation into a handoff document for another agent to pick up. Use when the user says "hand this off", "wrap up", "save context", "continue later", "pass this to another session", "I need to stop here", "pick this up later", or when a session is ending with unfinished work. Also use when context is getting long and the user wants to start fresh without losing progress.
argument-hint: What will the next session be used for?
---
Write a handoff document that lets a fresh agent continue this work without re-deriving any context. Save it to a path produced by `f=$(mktemp "${TMPDIR:-/tmp}handoff-XXXXXXXX") && mv "$f" "$f.md" && echo "$f.md"` (read the file before you write to it).
If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.
## What to capture
The goal is compression, not transcription. A good handoff is under 200 lines and gives the next agent everything it needs to start working immediately.
Include these sections (skip any that don't apply):
**Goal** — What the user is trying to accomplish, in one or two sentences. Include the "why" if it's not obvious from the task itself.
**Current state** — Where things stand right now: branch name, what's been built/changed, what works, what doesn't. Be specific — file paths, function names, test results.
**Decisions made** — Choices that were made during this session and their rationale. The next agent shouldn't re-litigate settled questions.
**What failed / dead ends** — Approaches that were tried and abandoned, and why. This prevents the next agent from repeating mistakes.
**Open questions / blockers** — Anything unresolved that needs the user's input or further investigation.
**Next steps** — Concrete actions for the next session, ordered by priority.
**Suggested skills** — Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
## What NOT to include
Do not duplicate content already captured in other artifacts — PRDs, plans, ADRs, issues, commits, diffs. Reference them by path or URL instead. The handoff supplements the commit history; it doesn't replace it.
Do not include verbatim code blocks unless they're critical context that isn't committed anywhere (e.g., a snippet the user pasted that informed a design choice).
Do not rehash the full conversation. Distill it.
© Nick Nisi · MIT · nicknisi/claude-plugins
Similar skills
All skills for Agent setup: memory, context, orchestration →handoff by other authors comes first.