# Handoff

> Write a durable handoff summary of this conversation to disk so a future session can resume it cleanly with /pickup. Trigger with /handoff [topic label], or when the user says they're stopping for now, switching machines, or wants the current state saved for later.

- Skill: `davemaynard/handoff` (Agent Skill)
- Install (CLI): `npx skillmds@latest add davemaynard/handoff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/davemaynard/handoff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: davemaynard (https://skillmd.com/u/davemaynard)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/davemaynard/handoff

---


# /handoff — save this conversation for a future session

Topic label (optional): $ARGUMENTS

Write a **handoff file** capturing the current state of this conversation so a future session
(with none of this context) can resume it with `/pickup`. Handoffs live in a central store so
many projects can coexist: `$HANDOFF_DIR` if set, otherwise `~/.claude/handoffs`.

## Steps

1. **Ensure the store exists** and get a timestamp:
   ```bash
   STORE="${HANDOFF_DIR:-$HOME/.claude/handoffs}"
   mkdir -p "$STORE"
   date +%Y-%m-%d-%H%M
   ```
2. **Build the slug** (this is what `/pickup` will match on, so make it descriptive):
   - If a topic label was given in `$ARGUMENTS`, kebab-case it (lowercase, spaces→`-`, strip punctuation).
   - Otherwise infer a 2–4 word kebab slug from what this conversation is actually about.
   - If the work centers on a specific repo/project, prefix the slug with that project's name
     (e.g. `acme-web-deploy`, `acme-web-blocks`). This keeps multiple projects distinct in the store.
3. **Write** `$STORE/<slug>__<YYYY-MM-DD-HHMM>.md` using the Write tool, following the
   template below. Be concrete and specific — a stranger should be able to act from it alone.
4. **Confirm** to the user: print the full file path and the exact resume command
   `/pickup <slug>` (use the slug, not the timestamp — `/pickup` finds the latest match).

## File template

```markdown
# Handoff — <human title> (<YYYY-MM-DD HH:MM>)

- **Slug:** <slug>   ·   **Resume with:** `/pickup <slug>`
- **Primary dir(s) / repo(s):** <absolute paths, e.g. ~/code/acme-web>
- **Related notes/docs:** <links or paths, if any>

## What this is about
<1–3 sentences: the goal and why.>

## Current state
<What's done and working right now. Be honest about what's half-done or unverified.>

## Key files & locations
<Absolute paths + one-line purpose for each file that matters. Include any URLs, ports,
running servers, or env vars in play.>

## Decisions made (and why)
<Bullets. Capture rationale so it isn't re-litigated. Note anything explicitly rejected.>

## Open questions / pending
<Anything awaiting a decision or blocked.>

## Next steps
<Ordered, actionable. The first item should be the obvious next thing to do.>

## Gotchas / environment
<Dev servers running, things that need the user's hands (auth, money), flaky steps, etc.>
```

## Rules

- **Don't dump the whole transcript** — synthesize. Favor state, decisions, and next steps over narration.
- **Use absolute paths** so they resolve from any future cwd.
- **Convert relative dates to absolute** ("today", "yesterday" → real dates).
- Note any **running processes / servers / URLs** explicitly so `/pickup` can re-verify them.
- If a handoff with the same slug already exists, **append `-v2`, `-v3`, …** to the slug rather than overwriting (timestamps already differentiate, but keep slugs readable).
- Keep it tight — one screen or two. This is a launchpad, not an archive.