建立 /handoff skill + SessionStart hook：解決多任務切換失焦

[atomchung]

背景

多任務並行時（切到別的 repo / 隔天回來 / /compact 之後）會「失去 context」，每次回來都要重新理解進度。/resume 只能還原本機 session，無法跨機器、跨 worktree，且在 /compact 之後對話細節已遺失。

社群 best practice 是 /handoff skill（手動寫筆記）+ SessionStart hook（自動載筆記） 的組合迴路。

詳細討論見 agent-context-best-practices.md §9（commit ca57842）。

---

本地實作步驟（複製貼上即可）

雲端容器無法持久化 ~/.claude/，以下都在你本機操作。

步驟 1：建立 /handoff skill

放在 ~/.claude/skills/handoff/SKILL.md（個人，所有專案可用）；如果想團隊共享，改放 <repo>/.claude/skills/handoff/SKILL.md。

---
description: Write a resume briefing for the next session. Use when stepping away from a task, switching projects, before /clear, or before closing the terminal. Produces .claude/HANDOFF.md so the next session (or another machine, or a teammate) can pick up without rebuilding context.
disable-model-invocation: true
allowed-tools: Read Write Bash(git status *) Bash(git diff --stat *)
---

# Handoff

Read the conversation so far and write `.claude/HANDOFF.md` so that opening a fresh session can resume this work in under 60 seconds.

## Output format

Plain sentences, **no markdown bullets, no invented content**. Exactly these five sections, in this order:

Handoff —

Updated:

Goal

Done

Open

<What is started but not finished, or queued.>

Next

<The single next action to take. One concrete step, not a menu.>

Watch out for

<Subtle things the next session would miss: a hidden constraint, a path
you almost broke, a decision you reversed, a TODO you left intentionally.
Omit the section if there is nothing.>

## Rules

- **Overwrite** `.claude/HANDOFF.md` (do not append). Stale lines are worse than no handoff.
- Total length **under 250 words**. If you can't fit, you're including too much explanation — keep facts, drop narration.
- Refer to files by path (e.g. `agent-context-best-practices.md:120`), not by description.
- Do **not** add a "summary of conversation" section. The five sections above are the whole file.
- Do **not** invent next steps that weren't discussed. If `Next` is unclear, write what *blocks* deciding it.

## After writing

Reply with one line: `Handoff written to .claude/HANDOFF.md (<word count> words).`
Do not echo the file contents back.

步驟 2：設定 SessionStart hook 自動載回

每個專案的 <repo>/.claude/settings.json（commit 進 git，團隊共享）：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "test -f .claude/HANDOFF.md && cat .claude/HANDOFF.md || true"
          }
        ]
      }
    ]
  }
}

這個 hook 在三個時點都跑：session 啟動 / /compact 後 / /resume 後。

步驟 3：個人筆記 gitignore

每個專案的 .gitignore 加：

# Personal handoff notes — local, per-machine
.claude/HANDOFF.md
.claude/settings.local.json
CLAUDE.local.md

---

驗收

1. 在某個 repo 打 /handoff → 看到 Handoff written to .claude/HANDOFF.md (XXX words).
2. 開新 session（或 /compact）→ Claude 開口前 HANDOFF 內容已在 context
3. cat .claude/HANDOFF.md 看內容是 5 區段、< 250 字

一次設好的 batch（可選）

如果想一鍵在很多 repo 都裝 hook + .gitignore，寫個小 script iterate over ~/Code/*，把 .claude/settings.json + .gitignore 行追加進去。Skill 只要在 ~/.claude/skills/handoff/ 裝一次就所有專案通用。

參考

• Skills | Claude Code Docs
• Hooks reference | Claude Code Docs
• I Built a /handoff Skill for Claude | YAKStack
• 內部討論：agent-context-best-practices.md §9