# Handoff

> Build or refresh handoff.md — a continuation doc that hands the next session (a future you, a teammate, or a run that resumes after compaction) the full picture so it keeps going instead of rebuilding context from scratch. Use when the user says "handoff", "/handoff", "write a handoff", "update the handoff", "hand off to next session", "session handoff", "save context for next time", or when wrap…

- **Type:** Skill
- **Install:** `agentstack add skill-napnap11-claude-skills-handoff`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [napnap11](https://agentstack.voostack.com/s/napnap11)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [napnap11](https://github.com/napnap11)
- **Source:** https://github.com/napnap11/claude-skills/tree/main/handoff

## Install

```sh
agentstack add skill-napnap11-claude-skills-handoff
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Session Handoff Skill

Produce or update `handoff.md` at the project root: a compact, skim-friendly picture of the current situation so the **next session is productive in seconds instead of minutes** — without re-deriving what's already known or re-breaking what already works.

**The richest source of material is this session's own recollection of what it did.** Write the handoff right here in the main conversation — do not hand the authoring off to a subagent, which carries none of the conversation's context. Tools exist only to pull durable repo facts that confirm or correct that recollection.

A handoff is neither a changelog nor a memory dump. It exists to answer four things for whoever picks up next: *Where do we stand? What just changed? What's still open? What's the first move?* Anything that doesn't serve one of those gets cut.

## Gather context first

This skill ships standalone, so it can't assume your project's conventions, house style, or preferences the way it could for its author. Before doing the main work:

1. **Auto-detect what you safely can** from the repo — language/stack, base branch, build/test commands, existing config and docs. Never ask for something you can read for yourself.
2. **Ask, don't assume, for the rest.** Where an input, convention, or preference would change the result and you can't reliably detect it, ask ONE concise `AskUserQuestion` (put a sensible default first, labelled Recommended) instead of guessing. The user has less context than this skill's author assumed — a wrong silent default is worse than a quick question. Don't ask about things you can detect, and don't ask more than you need.

For this skill, confirm up front (only the items you can't already detect):
- **Output path & filename** — default is `handoff.md` at the repo root; confirm if this project keeps continuation/session docs somewhere else or under a different name.
- **Commit or leave uncommitted** — auto-detect from `.gitignore`; `handoff.md` is usually per-session scratch left untracked, but confirm before staging if the project tracks such docs.
- **Focus / scope** — if `$ARGUMENTS` didn't name one, which in-flight thread the next session most needs carried forward (vs. a general "where we are" pass over everything).
- **Where open work and durable notes live** — which review / TODO / issue / notes files to point at; the house `PLAN_REVIEW_*` / `REVIEWED.md` / `TODOS.md` names may not exist here, so point at whatever this project actually uses instead of inventing them.

## Step 0 — create vs update

Look for `handoff.md` at the repo root (`ls handoff.md`):

- **Found → UPDATE it in place. Do NOT overwrite wholesale.** The expensive part is the operational context — re-verify commands, infra coordinates, traps, "do NOT do X" warnings — and preserving whatever is still true is the entire point. Then: refresh the dated header; swap "What shipped" for this session's work; **re-confirm or explicitly mark stale** every runtime value the previous handoff stated; carry over still-open follow-ups and drop the resolved ones; rewrite "Next session". If this session disproved something the old handoff claimed, call it out (`~~old~~ → corrected: …`) rather than quietly replacing it.
- **Missing → CREATE** one from the template below.

If `$ARGUMENTS` points at a focus (e.g. `handoff focus on the migration`), tilt the doc toward that thread while still answering all four questions.

## Step 1 — gather the state (facts, not impressions)

Replay the current conversation for what genuinely happened this session, then check it against the repo:

```bash
git branch --show-current
git log --oneline -15
git status --short
git log --oneline @{upstream}..HEAD 2>/dev/null                 # unpushed local commits
gh pr list --state open   --limit 10 2>/dev/null                # open PRs
gh pr list --state merged --limit 8  2>/dev/null                # recently merged
ls *REVIEW*.md REVIEWED.md TODOS.md handoff.md 2>/dev/null       # review artifacts + existing todos
```

Draw on these, highest priority first:
1. **The conversation itself** — what got decided, built, fixed, deferred, and *why*. Only the live session holds this, which is exactly why this skill can't run as a subagent.
2. **Open-work trackers** — whatever this project actually uses: a `TODOS.md`, review files (`PLAN_REVIEW_*.md`, `SCOPE_REVIEW_*.md`, `REVIEWED.md` if present), GitHub issues, or a `NOTES.md`. Detect what exists rather than assuming the house review-file names; cite them by name and don't restate what they already contain.
3. **Durable project notes** — any long-lived memory or notes file the project keeps for facts already recorded. Link to them; never copy their contents across.
4. **Deploy / runtime surface** — if the project has a `deploy.sh`, an `infra/` directory, or any live/deployed component (the project's CLAUDE.md or README usually says), capture the **Current state** section. For a library or CLI with no runtime, skip it and note build/test status instead.

**Confirm every cited fact before it goes in** — PR numbers, commit SHAs, file paths, host IPs, env-flag values. A handoff that points the next session at the wrong place, branch, or box is worse than none at all. For any runtime value you can't re-confirm right now, record it as `(last verified , re-check before trusting)` rather than asserting it as current.

## Step 2 — write the handoff

Front-load whatever prevents wasted effort and broken things. Trim the rest. Aim for **~1–2 screens**; a handoff nobody reads is dead weight. Include only the sections that apply:

```markdown
# Session Handoff

**Date:** 
**Branch:**  — 
**State:** 

---

## TL;DR

## Current state — verify before trusting   ← only if there's a live/deployed/stateful component
- **Infra:** .
- **Last verified ():** .
- **Re-verify:** ``
  (State is stale the moment it's written — this line is mandatory for anything live.)

## What shipped this session
| PR / commit | Content |
|---|---|
| #NN (merged) |  |
| `` |  |

## Open follow-ups
-  → tracked in `TODOS.md #N` / issue #N / ``. (Point, don't re-explain.)

## In-flight / not landed
- : .

## Gotchas / notes
- .

## Next session — start here
1. **** — .
2. …
```

## Style

- Skimmable: short bullets, **bold the load-bearing words**, tables for PR lists.
- Absolute dates only (turn "yesterday" / "next week" into actual dates).
- Provenance refs (PR numbers, commit SHAs, ticket IDs) are welcome here — `handoff.md` is throwaway per-session scratch, so naming them costs nothing. The code those refs point at, though, should still read clearly on its own.
- Name the **one** thing to tackle first, in plain terms. "Various cleanup remains" helps no one.
- Don't pad for the appearance of thoroughness. A small session earns a small handoff.

## Output

Write `handoff.md` to the repo root (or wherever this project keeps continuation/session docs, if it has a different convention — confirm rather than guess). Print a 2-line confirmation: what it now covers plus the named first step for next time. **Do not commit it unless asked** — `handoff.md` is usually left uncommitted (or gitignored) as per-session scratch; check `.gitignore` and the repo's convention before staging.

## When this fires on its own

It pairs well with context pressure: when a session has run long and is nearing compaction, offer to write the handoff before the context is lost. It complements any durable project-notes update — those hold the long-lived facts, while the handoff captures the volatile "where we are right now" the next session needs. Don't auto-write without a prompt; offer first.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [napnap11](https://github.com/napnap11)
- **Source:** [napnap11/claude-skills](https://github.com/napnap11/claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-napnap11-claude-skills-handoff
- Seller: https://agentstack.voostack.com/s/napnap11
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.