save

---
name: save
description: Pause work at a clean stopping point and get ready to continue in a fresh session — commit changes, write the work log, update memory, and leave a handoff note — as a page in the Cairn board's Handoff collection when one is set up, otherwise in .handoff/HANDOFF.md. If no work is left to hand over, wrap the task up instead (verify, commit, integrate, work log, memory). Always use this skill when the user wants to hand off, switch or restart sessions, says the context is getting large or full, wants to stop here before /clear, or wants to restart to load new skills, plugins or settings — even if they don't name the skill. Japanese phrasings count too, e.g. 「引き継ぎ」「ハンドオフ」「セッションを切り替えたい」「新しいセッションに移りたい」「コンテキストが増えてきた」「一度区切って」. Also use it to suggest a handoff when you notice the context window is running low. The counterpart for picking the work back up is handoff:resume.
---

# handoff:save — pause work and hand it to the next session

The Claude in the next session remembers nothing of this conversation. All it will have is the state of the repository (commits and files), the project's CLAUDE.md, auto-memory, and the handoff note this skill writes. So the point of this skill is to **move everything that exists only in the conversation into places the next Claude can read**. Above all, keep the things that cannot be recovered from the code: why things were done, what was tried and failed, and instructions the user gave in conversation.

This skill is often called when little context is left. Don't reread large files or widen the investigation; write up what the conversation already holds, quickly.

Write the contents of the handoff note and every message to the user in the language the user has been using in this session. The note's headings are the exception: keep them exactly as in the template in step 5, in English, without translating them, so that every session and every agent writes notes of the same shape.

## Running commands

Run one command at a time and read its output before the next one. Don't write commands that contain `$(`, `&&` or `||` (some sandboxes and headless agents refuse them); edit files with your file-editing tool.

## Where the note goes

The note goes to one of two places. Decide which before step 0 and use the same one for the whole run.

- **Cairn route**: the session has the MCP tools of Cairn, a shared board for agents (`get_overview`, `get_collection`, `query_pages`, `create_page`, `update_page`, ...; the server is usually named `cairn`), and the workspace has a collection set up for handoff notes. To check:
  1. Call `get_overview` and look in `collections` for one named `Handoff`
  2. Call `get_collection` on it and check that it has all of these properties: `project` (select), `status` (select with the options `open`, `resumed` and `closed`), `branch` (text), `date` (date) and `path` (text)

  If both checks pass, write the note as a page in `Handoff` following "The Cairn route" below, and don't create `.handoff/HANDOFF.md`.
- **File route**: everything else — no Cairn tools, no `Handoff` collection, or a property missing or of another type. Write `.handoff/HANDOFF.md` as described in the steps. Don't create or change the collection to make the Cairn route work; that is the user's setup.

If the Cairn tools are there but the check itself fails because Cairn can't be used right now (see "When Cairn can't be written"), you can't tell which route the user has set up. Follow "When Cairn can't be written" for the note instead of falling back to `.handoff/`.

## Steps

### 0. Decide whether there is work to hand over

First, check whether this session's work is finished.

- **Nothing to hand over**: every request from the user is done, and there is no next step and no decision waiting on the user. Follow "When there is nothing to hand over" below to wrap the task up. Don't write a handoff note (an empty note would make the next session try to resume finished work)
- **Work to hand over**: there is remaining work or at least one pending decision. Continue from step 1
- If unsure, treat it as work to hand over. An extra note does little harm; dropped work goes unnoticed in the next session

### 1. Find a stopping point

- Don't start new tasks. If the step in progress will be done in a few minutes, finish it. If not, get back to a state that isn't broken (sometimes it is better not to commit a half-done edit and record it in the note as in progress)
- If subagents or background jobs are running, wait for them to finish and collect their results — once the session closes, their results can no longer be received. If something will take very long (tens of minutes or more), ask the user whether to wait or stop it and record it. If you stop it, write in the note what it was doing and how far it got
- Don't force decisions that are the user's to make. Put them under "Pending decisions" in the note

### 2. Commit changes

Uncommitted local changes leave the next session unable to tell who changed what and why. Commit following the git rules in the project's CLAUDE.md.

- Check `git status` in the main working tree and in every worktree in use (`git worktree list`)
- Unfinished work may be committed with a message that marks it as WIP (e.g. `wip: <topic>, partway (for handoff)`)
- Push or merge only where you would in normal work. Don't put unfinished work into the merge target just for the handoff
- If you commit while tests are failing, say so in the note
- If the folder isn't under git, skip this step

### 3. Write the work log (if the project has a rule for it)

If the project's CLAUDE.md has a rule for work logs (e.g. `docs/worklog/`), write this session's entry following it and include it in the commit. If the rule keeps the log outside the repository (for example as a page on the Cairn board), write it there; there is nothing to commit for it. If there is no rule, don't write one (the handoff note is enough).

A work log keeps "lessons for future development"; the handoff note keeps "the state the next session needs to start right away". They serve different purposes. Don't write the same content at length in both; the note can just point to the log file.

### 4. Update memory

Save to auto-memory what you learned in this session that **will stay useful after this task is over**: the user's preferences and instructions, circumstances of the project, pitfalls likely to bite again. Check for an existing memory that covers it and update that instead of duplicating.

Don't put information that only matters during this task — how far you got, what comes next — into memory. That belongs in the handoff note.

### 5. Write the handoff note

On the Cairn route, write the note as described in "The Cairn route" below (same shape as the template here) and skip the `.handoff/` instructions in this step. On the file route:

Save it as `.handoff/HANDOFF.md` in **the folder this session was started in** (the primary working directory). The next session is assumed to start in the same folder.

- If a `HANDOFF.md` already exists, move it to `.handoff/archive/<YYYY-MM-DD-HHMM>.md` before writing the new one
- In a git repository, keep `.handoff/` out of git without touching the project's `.gitignore` (changing it would need a commit): put a file `.handoff/.gitignore` containing the single line `*`, if it isn't there yet. It makes git ignore everything in `.handoff/`, itself included, so nothing shows up in `git status`. Write it with your file-editing tool. (Don't write to `.git/info/exclude` instead: many agents and sandboxes refuse writes inside `.git/`.)

Write the note in this shape. Keep the title, every heading and the labels at the top (`Created:`, `Working folder:`, ...) as they are here (don't translate or rename them), and write the text under them in the user's language. Don't leave out any section: the note always has all seven — `## Goal`, `## Done`, `## Next steps`, `## Pending decisions`, `## Key context`, `## State of the workspace` and `## Files to read`. If a section has nothing to say, keep its heading and write "None" under it (a missing or empty section leaves the next Claude unable to tell whether it was forgotten or there really is nothing).

```markdown
# Handoff note

- Created: YYYY-MM-DD HH:MM
- Working folder: /path/to/project
- Branch / HEAD: main / abc1234 (first line of the commit message)
- Reason for pausing: context size / loading new skills / other

## Goal
What this whole piece of work is trying to achieve. The user's original request, as close to their own words as possible.

## Done
- Bullet points. Add commit hashes where there are commits

## Next steps
1. Make the first step concrete enough to start without hesitation (which file, what change, which command)
2. The steps after it
(If there is a plan document, say which task to resume from and point to the file)

## Pending decisions
- Things that need the user's confirmation, and the work held back until they decide

## Key context
- Decisions and the reasons for them (and who made them)
- What was tried and didn't work, and why
- Instructions and preferences the user gave in conversation that didn't go into memory
- Caveats and pitfalls

## State of the workspace
- Worktrees and work branches, and the state of each (committed / not merged, etc.)
- Jobs that were stopped (subagents, background jobs) and how far they got
- Test status (passing / failing tests and why)

## Files to read
- Files the next session should read first (plans, design docs, work logs, key source files)
```

A yardstick while writing: could the next Claude, reading only this note and the files it points to, start step 1 of "Next steps" without asking the user anything? If not, work out what is missing and add it.

### 6. Tell the user

Finish with a short summary:

- What you tidied up (commits, work log, memory, where the note is — the file path, or the Cairn page's title and `url`)
- A one-line summary of the next step, and the list of pending decisions if any
- How to start the new session:
  - To free up context only: `/clear`, then `/handoff:resume`
  - To load new skills, plugins or settings: quit Claude Code, start `claude` again in the same folder, then `/handoff:resume` (`/clear` does not reload some of these)

## When there is nothing to hand over

If the work is finished, don't hand it over — tidy up the way you would at the end of any task, and complete it. The goal is that the next session inherits nothing and can start from a clean slate.

1. **Confirm it is done**: run whatever the project uses to confirm completion, such as tests or a build, and check that it passes. If it doesn't, the work isn't finished; go back to step 0 and treat it as work to hand over
2. **Commit and integrate**: commit the changes and, following the git rules in the project's CLAUDE.md, merge and push as you normally would. Clean up worktrees and work branches that have served their purpose. Don't perform operations the rules say need the user's confirmation (publishing, releases, etc.) on your own; ask the user
3. **Work log**: if the project has a rule for it, write the entry following it, as in step 3 — include it in the commit when the log is a file in the repository; when the rule keeps it outside (for example on the Cairn board), write it there
4. **Memory**: save what will stay useful, by the same standard as step 4
5. **Clear out the old handoff note**, so the next session doesn't resume work that is already done:
   - File route: if a `.handoff/HANDOFF.md` is left over, move it to `.handoff/archive/`
   - Cairn route: set every `open` and `resumed` page of this project and branch to `closed` (see "The Cairn route"). Don't write a new page
6. **Tell the user**: say the work is complete and briefly list what you tidied up (commits, merge, push, work log, memory). Tell them the new session can start with just `/clear` or a restart of Claude Code, and that `/handoff:resume` is not needed

## The Cairn route

Each handoff is one page in the `Handoff` collection. Several sessions (for example one per git worktree) can share a workspace, so notes are kept apart by **project and branch**: only ever close or replace pages with the same project and branch as this session, and leave the others alone.

### Values

- **project**: in a git repository, the name of the folder that holds the main checkout — the same in every worktree. Run `git rev-parse --path-format=absolute --git-common-dir`, read the path it prints (for example `/work/myapp/.git`), and take the name of the folder that contains it (`myapp`).

  Outside git, the name of the folder this session was started in
- **status**: `open` (waiting for the next session), `resumed` (a session picked it up), `closed` (done with)
- **branch**: `git branch --show-current`. Leave it out outside git or on a detached HEAD
- **Handing over to another folder**: normally the next session starts in this same folder, and the values above apply. Only when it has been settled that the next session will start in a different project folder that already exists (for example, you planned a new project from a parent folder, created its repository, and the user will continue inside it), use that project's name for `project` and `main` for `branch`, so that its resume finds the note. Don't create the folder just for this
- **date**: the time of writing in UTC, `date -u +%Y-%m-%dT%H:%M:%SZ`
- **path**: leave it out (it is for notes brought in from elsewhere)
- **title**: `<project> <branch> <YYYY-MM-DD HH:MM in local time> <one-line summary>`; drop `<branch>` when it is empty
- **body**: the note, in the same shape as the template in step 5: the same English headings, all seven sections ("None" for an empty one), and the text under them in the user's language

`project` is a select property: if the name is not one of its options yet, add it first with `update_collection` (`add_options: [{"property": "project", "options": ["<name>"]}]`). Add only that name.

### Finding this session's pages

Use `query_pages` on the `Handoff` collection with a filter like this (for an empty branch, use `{"property": "branch", "op": "is_empty"}` instead of the `eq` on `branch`):

```json
{"and": [
  {"property": "project", "op": "eq", "value": "<project>"},
  {"property": "branch", "op": "eq", "value": "<branch>"},
  {"or": [{"property": "status", "op": "eq", "value": "open"},
          {"property": "status", "op": "eq", "value": "resumed"}]}
]}
```

### Writing the note (step 5)

1. Find this session's `open` and `resumed` pages and set each to `closed` with `update_page` (`values: {"status": "closed"}`, `expected_updated_at` set to the page's `updated_at`). On a conflict, read the page again and retry
2. Create the new page with `create_page` in `Handoff`, with `status` `open` and the values above
3. Tell the user the page's title and `url`

When there is nothing to hand over, do only step 1.

### When Cairn can't be written

Cairn can't be used when its MCP server doesn't connect or the calls fail, when `get_overview` reports `access_mode.mode` as `read_only`, or when a write fails for a reason on the workspace's side (error codes such as `read_only`, `busy`, `internal`, `workspace_replaced`). Errors about the call itself (`invalid_argument`, `invalid_value`, `not_found`) are not that: fix the call and try again.

Don't fall back to `.handoff/HANDOFF.md` silently — the next session would look for the note in Cairn. Instead:

1. If a `create_page` call failed without a clear answer (for example the response was cut off), first check with `query_pages` whether the page was created after all. If it was, you are done
2. Save the note as a pending file in `.cairn-pending/` at the top of the working tree — the folder `git rev-parse --show-toplevel` prints (in a worktree, that worktree's top folder); outside git, the folder this session was started in. Name it `<YYYY-MM-DD>-handoff-<short-topic>.md` (add `-2`, `-3`, ... if the name is taken). Start it with front matter holding the values, then the note:

   ```markdown
   ---
   kind: handoff
   pending_id: <ULID>
   title: <title>
   project: <project>
   status: open
   branch: <branch>
   date: <date>
   ---
   # Handoff note
   ...
   ```

   Write each value as it is, after `key: `. Leave out the `branch:` line when the branch is empty. If a value starts with a quote character (`"` or `'`) or has spaces at either end, write it as a JSON string instead (`title: "\"quoted\" title"`): a value wrapped in quotes is read with the quotes taken off. Make the `pending_id` with:

   ```bash
   python3 -c "print((lambda n: ''.join('0123456789ABCDEFGHJKMNPQRSTVWXYZ'[n // 32 ** i % 32] for i in range(25, -1, -1)))(int(__import__('time').time() * 1000) * 2 ** 80 + int.from_bytes(__import__('os').urandom(10), 'big')))"
   ```

3. After the pending file is written, in a git repository, keep `.cairn-pending/` out of git the same way as `.handoff/`: put a file `.cairn-pending/.gitignore` containing the single line `*`, if it isn't there yet
4. Tell the user that Cairn could not be written, where the pending file is, and which old pages could not be closed. Whoever moves the file into Cairn later creates the page with `path` set to `pending:<pending_id>` (after checking with `query_pages` that no page has that `path` yet), then deletes the file

• SKILL.md 17 KB
• evals/handoff-cairn/case.yaml 1 KB
• evals/handoff-cairn/place-files.sh 4 KB
• evals/handoff-cairn/prompt.md 1 KB
• evals/handoff-cairn/files/session-transcript.md 1 KB
• evals/handoff-cairn/graders/01-committed.md 1 KB
• evals/handoff-cairn/graders/02-no-handoff-file.md 1 KB
• evals/handoff-cairn/graders/03-one-new-open.md 1 KB
• evals/handoff-cairn/graders/04-old-closed.md 1 KB
• evals/handoff-cairn/graders/05-others-untouched.md 1 KB
• evals/handoff-cairn/graders/06-note-content.md 1 KB
• evals/handoff-cairn/graders/07-tells-user.md 1 KB
• evals/handoff-cairn-new-project/case.yaml 1 KB
• evals/handoff-cairn-new-project/place-files.sh 1 KB
• evals/handoff-cairn-new-project/prompt.md 1 KB
• evals/handoff-cairn-new-project/files/session-transcript.md 1 KB
• evals/handoff-cairn-new-project/graders/01-no-git-init.md 1 KB
• evals/handoff-cairn-new-project/graders/02-no-handoff-file.md 1 KB
• evals/handoff-cairn-new-project/graders/03-option-added.md 1 KB
• evals/handoff-cairn-new-project/graders/04-one-open.md 1 KB
• evals/handoff-cairn-new-project/graders/05-decisions.md 1 KB
• evals/handoff-cairn-new-project/graders/06-other-untouched.md 1 KB
• evals/handoff-cairn-new-project/graders/07-restart-not-clear.md 1 KB
• evals/handoff-mid-task-git/case.yaml 1 KB
• evals/handoff-mid-task-git/place-files.sh 4 KB
• evals/handoff-mid-task-git/prompt.md 1 KB
• evals/handoff-mid-task-git/files/session-transcript.md 2 KB
• evals/handoff-mid-task-git/graders/01-main-committed.md 1 KB
• evals/handoff-mid-task-git/graders/02-worktree-committed.md 1 KB
• evals/handoff-mid-task-git/graders/03-not-merged.md 1 KB
• evals/handoff-mid-task-git/graders/04-worklog.md 1 KB
• evals/handoff-mid-task-git/graders/05-handoff-file-excluded.md 1 KB
• evals/handoff-mid-task-git/graders/06-pending-decision.md 1 KB
• evals/handoff-mid-task-git/graders/07-rejected-and-instructions.md 1 KB
• evals/handoff-mid-task-git/graders/08-concrete-next-step.md 1 KB
• evals/handoff-mid-task-git/graders/09-memory-durable-only.md 1 KB
• evals/handoff-mid-task-git/graders/10-resume-instructions.md 1 KB
• evals/handoff-reload-non-git/case.yaml 1 KB
• evals/handoff-reload-non-git/place-files.sh 1 KB
• evals/handoff-reload-non-git/prompt.md 1 KB
• evals/handoff-reload-non-git/files/session-transcript.md 1 KB
• evals/handoff-reload-non-git/graders/01-no-git-init.md 1 KB
• evals/handoff-reload-non-git/graders/02-handoff-file.md 1 KB
• evals/handoff-reload-non-git/graders/03-decisions.md 1 KB
• evals/handoff-reload-non-git/graders/04-pending-widget.md 1 KB
• evals/handoff-reload-non-git/graders/05-next-step.md 1 KB
• evals/handoff-reload-non-git/graders/06-restart-not-clear.md 1 KB
• evals/handoff-work-complete/case.yaml 1 KB
• evals/handoff-work-complete/place-files.sh 3 KB
• evals/handoff-work-complete/prompt.md 1 KB
• evals/handoff-work-complete/files/session-transcript.md 1 KB
• evals/handoff-work-complete/graders/01-no-new-handoff.md 1 KB
• evals/handoff-work-complete/graders/02-stale-archived.md 1 KB
• evals/handoff-work-complete/graders/03-tests-run.md 1 KB
• evals/handoff-work-complete/graders/04-merged.md 1 KB
• evals/handoff-work-complete/graders/05-pushed.md 1 KB
• evals/handoff-work-complete/graders/06-worktree-cleaned.md 1 KB
• evals/handoff-work-complete/graders/07-worklog.md 1 KB
• evals/handoff-work-complete/graders/08-tells-complete.md 1 KB