handoff

Run without pausing

Invoking this skill is the user's request to run every step below — reading files, running git and shell commands, creating the handoffs/ folder, writing the handoff document, and appending to .gitignore. Run the whole skill start to finish without stopping to ask questions: not about the destination, not about the filename, not about what to include. If something is ambiguous, make the sensible call and note it in the document rather than stopping to ask. Claude Code's own permission settings still apply: if a tool call needs approval under those settings, the harness will prompt for it.

What this skill does

A session ends and everything that made it productive — why a path was chosen, what was already tried and failed, which file you were halfway through editing — disappears with the context window. The handoff is a letter to the next session.

The bar to aim for: a fresh Claude, with no memory of this conversation, reads the file and can continue the work without asking the user a single "wait, what were we doing?" question. Anything that fails that bar is worth writing down; anything the next session can trivially derive by reading the code is not.

Step 1 — Check the trigger message for an inline open task

The message that triggered this skill sometimes carries more than the trigger itself — e.g. /handoff add task: test the CSV export or /handoff — also note we still need to update the README. Scan the exact message that invoked /handoff (not the whole conversation) for a marker phrase — "add task", "open task", "also add", "note task" — case-insensitive. Everything after the marker, up to the end of the message or the next marker if more than one appears, becomes one open-task entry.

These are separate from Next Steps: Next Steps continue the interrupted work itself; an inline open task is a distinct ask that surfaced but was never started (e.g. "also test X" while you were mid-way through Y). Keep them in their own list, captured for Step 5's Open Tasks section. If no marker is present, there is nothing to capture — don't invent a task from context.

Step 2 — Reconstruct what actually happened

Figure out what changed, in this order:

1. Git repo — git status, git diff HEAD (or git diff if nothing is staged), and git log --oneline -10.
2. No git — look at recently modified files, e.g.
   • macOS / Linux / Git Bash: find . -type f -mmin -720 -not -path '*/node_modules/*' -not -path '*/.git/*' | head -30
   • Windows PowerShell: Get-ChildItem -Recurse -File -Include *.js,*.py,*.md,*.html,*.json | Where-Object { $_.LastWriteTime -gt (Get-Date).AddHours(-12) -and $_.FullName -notmatch 'node_modules|\.git' } | Sort-Object LastWriteTime -Descending | Select-Object -First 30
3. Conversation context — if neither is conclusive, rely on what you know from this session.

Git and the filesystem tell you what changed. They can't tell you the things that only exist in this conversation, and those are usually the most valuable part of the handoff:

• Decisions made, and — just as important — options considered and rejected, with the reason. Without this the next session cheerfully re-proposes the idea the user already turned down.
• Dead ends already tried, so nobody pays for the same mistake twice.
• The exact stopping point: not "working on auth" but "validateToken() in middleware/auth.js returns the decoded payload, but nothing calls it yet — the route wiring in routes/api.js is untouched."
• Anything the user said about constraints, preferences, or environment.

Step 3 — Destination

Always the session's project folder — the folder the chat was opened in: <project>/handoffs/. Create the folder if it doesn't exist. Don't ask, don't search for a "better" project root — predictable beats clever, and the user can move the file if they want it elsewhere.

Never write a handoff into the global ~/.claude folder (or anything inside it), even when the session's work edited skills, plugins or settings there. /resume-handoff is run from the project folder and looks only there, so a handoff written under ~/.claude is effectively lost.

The shell's current directory is not a safe guide: a cd in an earlier command can leave it inside ~/.claude or a skill folder. Use the folder the session started in (the first "Primary working directory", also encoded in the ~/.claude/projects/<slug>/ transcript path). If that folder itself is inside ~/.claude, ask the user which project folder to use — that is the one case where asking beats guessing.

Step 4 — Name the file

Format: YYYY-MM-DD_HH-<1-3-word-topic>.md — date, hour (no minutes), and a short lowercase kebab-case topic.

2026-08-11_10-auth-middleware.md
2026-08-11_15-csv-export.md

Get the real timestamp from the system rather than guessing: date +%Y-%m-%d_%H (macOS / Linux / Git Bash) or Get-Date -Format "yyyy-MM-dd_HH" (Windows PowerShell). If that exact filename already exists, append -2, -3, and so on — never overwrite an existing handoff, since the one on disk may be the only surviving record of an earlier session.

The ISO ordering here is deliberate: it makes the newest handoff the one that sorts last, which is how resume-handoff finds it. Keep the filename in this format even if the user prefers another date format elsewhere. The Date & Time line inside the document can follow the user's preferred date format (check CLAUDE.md for a date convention); default to YYYY-MM-DD HH:MM if none is set.

Step 5 — Write the document

The **Handoff-Status:** line directly under the H1 is a machine-readable lifecycle marker: open here, resumed <date time> once resume-handoff loads it, and complete <date time> if your end-of-session step marks the work finished. A script can read it, for example to move completed handoffs into archive/handoffs/. Always write it exactly as open — never invent another value.

Use this structure. The next session (and the resume-handoff skill) looks for these headings by name, so keep them as-is even when a section is thin:

# Session Handoff: [Brief Topic]
**Handoff-Status:** open
**Date & Time:** [YYYY-MM-DD HH:MM, or the user's preferred date format]

## 🎯 Goal
[1-2 sentences on the ultimate aim of the feature/project being worked on]

## 🛑 Constraints & Environment
[Specific rules, active constraints, architectural decisions, environment
quirks. e.g. "React 18 strict mode"]

## 📝 Current State
**✅ Completed:**
- [Specific task — include file paths and config changes]
- [Specific task]

**🚧 In Progress:**
- [Exact state of the current unfinished task. If none, write "None."]

## 🧠 Key Learnings & Gotchas
[Crucial context the next session MUST know to avoid repeating mistakes.
e.g. "The API needs the X-Auth header, not Authorization",
"Options A and B were rejected because …"]

## 📂 Files to Review on Resume
[2-4 critical files the next session should read immediately to orient itself]

## ⏭️ Next Steps
[Numbered, highly specific, executable steps. If the work is finished,
write exactly: "There are no next steps."]

## 📌 Open Tasks
[Only include this heading when at least one task was captured in Step 1 —
one bullet per task, in the user's own words. Omit the entire section,
heading included, when there are none. These are asks that came up but
haven't been started yet — not a restatement of Next Steps.]

Be relentlessly specific. A vague handoff is worse than none, because it looks like context while carrying none. Name exact file paths (as clickable relative markdown links, e.g. [server.js](server.js) or [auth.js:42](middleware/auth.js#L42)), exact function and variable names, and exact commands including their flags. Phrases like "fixed the bug", "cleaned things up", "various changes", or "refactored some code" carry no information — if you catch yourself writing one, replace it with what actually happened.

Example — In Progress

Weak: Working on the login fix.

Strong: Rewrote validateToken() in [middleware/auth.js](middleware/auth.js) to return the decoded payload instead of a boolean. The three call sites in [routes/api.js](routes/api.js) still expect a boolean and will silently treat the payload object as truthy — they have NOT been updated yet. Start there.

Example — Next Steps

Weak: 1. Finish the auth work. 2. Test it.

Strong: 1. Update the three validateToken() call sites in [routes/api.js](routes/api.js) (lines 22, 48, 91) to read req.user from the returned payload. 2. Run npm test -- auth.test.js; the "rejects expired token" case is expected to fail until step 1 lands.

Never write "wait for the user's go" as a Next Step, Goal or Constraint. Running /resume-handoff is the go, so a wait step makes the next session stall for approval the user already gave. If the work is a plan or design the user hasn't signed off yet, record that as state ("design reviewed, nothing built yet") and make step 1 the first real build action. Real gates (push, deploy, delete, spending budget the user said is exhausted) are still worth naming — on the step they guard, not as a blanket wait.

If the "Files to Review on Resume" list would be more than four files, you're probably listing everything you touched rather than the few files that orient someone. Pick the ones that explain the shape of the work.

Step 6 — Secret hygiene, then write

Before writing, check what you're about to commit to disk. A handoff is a plain file that may get synced, zipped, or committed, so it should never contain:

• API keys, tokens, passwords, connection strings, or service-account JSON — refer to them by name and location instead ("the service-account key at config/service-account.json", "the value of API_KEY_PATH").
• Personal data — customer or employee names, salaries, IDs. Describe the query or the shape of the data, not the rows.

Then write the file. Afterwards, if the project is a git repo (.git exists), make sure handoffs/ is listed in .gitignore — append it under a # Session handoffs comment if missing, and do nothing if it's already there. Handoffs are personal working notes and rarely belong in a shared repo.

Step 7 — Confirm

Report in five lines or fewer — what was written, where, and how to load it:

Handoff saved → [handoffs/2026-08-11_10-auth-middleware.md](handoffs/2026-08-11_10-auth-middleware.md)
Topic: JWT middleware refactor — 3 call sites still to update
Next session: say "resume the handoff" (runs the resume-handoff skill), or "read the newest file in handoffs/ and continue"

Add a fourth line only if something genuinely needs flagging (e.g. "Added handoffs/ to .gitignore", or "Captured 1 open task: test the CSV export" if Step 1 found one). Don't restate the document's contents — the whole point is that they're in the file.

Relationship to the done skill

These are complementary and shouldn't be confused (done is a separate skill in the same marketplace — this skill works fine without it):

Running both is fine and the order doesn't matter. When the user asks only for a handoff, don't run done's commit and push machinery — writing a file is the entire job here.