handoff

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Handoff — Pass The Baton

Handoff — 工作交接棒

Summarize the current in-context conversation into a handoff a fresh agent (or future-you) can pick up without re-reading the session. Two output modes:

Inline mode (default) — render the handoff as Markdown directly in chat. Nothing else. The output IS the handoff.
Doc mode — write the handoff to a per-project file and print only two lines in chat: a link to the file and a copy-paste shortcut for the next session.

将当前上下文对话总结为交接文档，让新的Agent（或未来的你）无需重读会话即可接手工作。支持两种输出模式：

内嵌模式（默认）——直接在聊天中以Markdown格式渲染交接文档，无其他内容，输出内容即为交接文档本身。
文档模式——将交接文档写入项目专属文件，并仅在聊天中输出两行内容：文件链接以及用于开启下一轮会话的复制粘贴快捷指令。

Hard Rules

硬性规则

No preamble. Do not say "Here's the handoff" or summarize what you're about to write. The output is the handoff itself.
No duplication. If a fact is captured in a committed file, plan, PRD, issue, PR, or diff, link or path-reference it. Do not restate it.
No fabrication. Every fact in the handoff comes from the in-context conversation, files you read this session, or tool output you observed. Don't invent decisions, file paths, or commit messages. Provenance is the easiest thing to fake and the hardest to catch: a commit hash, a date, a version, or a "this broke in" claim appears only if a command returned it in this session. No result means the claim is dropped, not softened into "has likely been broken for a while".
Redact secrets. Never include API keys, tokens, passwords, PII, or credentials visible in the conversation. If a secret is load-bearing context, reference where it lives (env var name, 1Password item, secret manager path) instead of pasting it.
Empty sections never render. Pick from the section pool only what applies. If only Goal and Next step exist, that's the whole handoff.

无开场白：不得使用“这是交接文档”之类的表述，也无需概述即将撰写的内容，输出内容即为交接文档本身。
无重复内容：若某个事实已记录在已提交文件、计划文档、PRD、Issue、PR或差异文件中，只需链接或引用其路径，无需重述内容。
无虚构内容：交接文档中的所有事实均来自上下文对话、本次会话中读取的文件或观察到的工具输出。不得编造决策、文件路径或提交信息。来源信息最易造假也最难核查：提交哈希、日期、版本或“此处出现故障”的表述仅当会话中执行的命令返回该信息时才可提及。若无相关结果，则直接删除该表述，不得弱化处理为“可能已故障一段时间”。
隐藏敏感信息：不得包含对话中出现的API密钥、令牌、密码、个人身份信息（PII）或凭证。若敏感信息是关键上下文，只需引用其存储位置（如环境变量名称、1Password条目、密钥管理器路径），而非直接粘贴内容。
不渲染空章节：仅从章节库中选择适用的内容。若只有“目标”和“下一步”章节有内容，则交接文档仅包含这两部分。

Argument parsing

参数解析

The skill accepts a free-form argument string (

$ARGUMENTS

). Parse it once:

Mode keyword. If the tokens contain any of
```
doc
```
,
```
document
```
, or
```
--doc
```
(case-insensitive, as a standalone token), switch to doc mode and remove that token. Otherwise inline mode.
Focus. The remaining tokens, joined with spaces, become the focus string. The focus slants what the handoff emphasizes and seeds the filename slug. Empty focus is fine — the handoff still works.

Examples:

Invocation	Mode	Focus
`/handoff`	inline	(none)
`/handoff fix login bug`	inline	`fix login bug`
`/handoff doc`	doc	(none)
`/handoff doc fix login bug`	doc	`fix login bug`
`/handoff fix the login bug --doc`	doc	`fix the login bug`

该技能接受自由格式的参数字符串（

$ARGUMENTS

），解析规则如下：

模式关键字：若参数中包含
```
doc
```
、
```
document
```
或
```
--doc
```
（不区分大小写，作为独立令牌），则切换至文档模式并移除该令牌；否则使用内嵌模式。
聚焦主题：剩余令牌拼接为字符串即为聚焦主题，它决定了交接文档的重点方向，并作为文件名标识的基础。聚焦主题为空也可正常生成交接文档。

示例：

Invocation	Mode	Focus
`/handoff`	inline	(none)
`/handoff fix login bug`	inline	`fix login bug`
`/handoff doc`	doc	(none)
`/handoff doc fix login bug`	doc	`fix login bug`
`/handoff fix the login bug --doc`	doc	`fix the login bug`

Section pool

章节库

Pick from this pool. Include a section only if you actually have content for it from the conversation. Order them as listed.

Core (almost always present)

Goal — what the user wants, in one or two sentences. Top-level intent.
Where we are — project path, branch, working-tree state (clean / dirty / staged), last commit hash + subject. One short paragraph or a tight list.
What's been decided — design choices, assumptions adopted, scope cuts. Prevents the next session from re-litigating settled questions.
Next step — the specific concrete action the next session should take first. What "progress" means from here.

Conditional (only when applicable)

Problem & repro — bug sessions: failure, reproduction steps, expected vs actual.
Findings — discoveries from this session that aren't yet captured in code or commits.
Tried & ruled out — paths explored and dropped, with the reason. Stops the next agent re-walking dead ends.
Open questions — gaps the previous session didn't close.
Gotchas — non-obvious constraints learned the hard way.
References — paths and URLs to issues, PRs, plans, ADRs, diffs. Pointers, not copies.
Suggested skills — by name (e.g.
```
superpowers:systematic-debugging
```
,
```
dev:gh-actions-debug
```
). One short line each — what the next agent might reach for, why.

Deliberately not standalone sections

"Impact" — folds into Goal if it matters.
"Changes made" — that's what
```
git log
```
/
```
git diff
```
is for. Reference the branch and commits under Where we are / References.
"Summary of what we did" — narrative recap of the session is noise. The core sections already say where we ended up.

从以下章节中选择内容，仅包含对话中有对应信息的章节，并按所列顺序排列。

核心章节（几乎必选）

目标：用1-2句话描述用户需求，即核心意图。
当前进度：项目路径、分支、工作区状态（干净/未提交/已暂存）、最后一次提交的哈希值及主题。可采用简短段落或紧凑列表形式呈现。
已确定事项：设计方案、采纳的假设、范围缩减内容。避免下一轮会话重复讨论已解决的问题。
下一步行动：下一轮会话应优先执行的具体操作，明确当前阶段的“进展”定义。

条件章节（仅适用于对应场景）

问题与复现步骤：针对Bug排查会话：故障现象、复现步骤、预期结果与实际结果对比。
发现内容：本次会话中发现的尚未记录到代码或提交中的信息。
已尝试并排除的方案：已探索但被放弃的路径及原因，避免后续Agent重复走弯路。
未解决问题：上一轮会话未解决的疑问。
注意事项：通过实践总结出的非直观约束条件。
参考资料：指向Issue、PR、计划文档、架构决策记录（ADR）、差异文件的路径或URL，仅提供链接，不复制内容。
推荐技能：按名称列出（如
```
superpowers:systematic-debugging
```
、
```
dev:gh-actions-debug
```
），每项用简短说明解释后续Agent为何需要使用该技能。

不设为独立章节的内容

“影响范围”：若重要则并入“目标”章节。
“已做修改”：此类信息可通过
```
git log
```
/
```
git diff
```
查看，只需在“当前进度”或“参考资料”章节中引用分支和提交记录即可。
“会话总结”：会话的叙事性回顾属于冗余内容，核心章节已明确当前所处阶段。

Inline mode

内嵌模式

Render the handoff directly as Markdown in chat. No code-fence wrapper.

Start with:

undefined

直接在聊天中以Markdown格式渲染交接文档，无需代码块包裹。

开头格式如下：

undefined

Handoff

<project-name> · <branch> · <YYYY-MM-DD HH:MM>


Then the applicable sections, each as `## Section name` followed by its
content. Do not print a trailing summary, sign-off, or question.

<project-name> · <branch> · <YYYY-MM-DD HH:MM>


随后是适用的章节，每个章节以`## 章节名称`开头，后跟内容。不得添加结尾总结、签名或疑问。

Doc mode

文档模式

Resolve the encoded cwd: take the absolute working directory and replace every
```
/
```
with
```
-
```
. Example:
```
/Users/foo/repo/proj
```
→
```
-Users-foo-repo-proj
```
.
Build the filename:
```
YYYY-MM-DD-HHMM[-slug].md
```
, local time. Slug is derived from the focus string if present:
- Lowercase, replace non-alphanumeric runs with
```
-
```
  , trim leading/trailing
```
-
```
  , collapse repeats, cap at ~40 chars. Use the first 4–6 meaningful words.
- Omit the slug entirely if focus is empty.

Target path — use the first directory that matches the host you are running in:

Host	Base directory
Claude Code	`~/.claude/projects/<encoded-cwd>/handoff/`
Codex	`~/.codex/projects/<encoded-cwd>/handoff/`
OpenCode	`${XDG_CONFIG_HOME:-~/.config}/opencode/projects/<encoded-cwd>/handoff/`
pi	`~/.pi/agent/projects/<encoded-cwd>/handoff/`
Unknown	`.tmp/handoff/` in the current project

If you cannot tell which host you are in, prefer the project-local

.tmp/handoff/

path over guessing a home directory — a handoff written somewhere the user cannot find is worse than one in the repo.

Create the
```
handoff/
```
directory if needed.
On collision (same filename), suffix with
```
-2
```
,
```
-3
```
, … before
```
.md
```
.
Write the same Markdown body as inline mode to the file.
Print to chat exactly two lines, nothing else:
```
[<filename>](<absolute-path>)
Read @<absolute-path> and continue the work.
```
The first line renders as a clickable link in hosts that support it; the second is the copy-paste shortcut for starting the next session.

编码当前工作目录（cwd）：取绝对工作目录，将所有
```
/
```
替换为
```
-
```
。示例：
```
/Users/foo/repo/proj
```
→
```
-Users-foo-repo-proj
```
。
生成文件名：采用本地时间格式
```
YYYY-MM-DD-HHMM[-slug].md
```
。若存在聚焦主题，则从中生成标识（slug）：
- 转为小写，将非字母数字序列替换为
```
-
```
  ，去除首尾
```
-
```
  ，合并重复的
```
-
```
  ，长度限制约40字符，取前4-6个有意义的单词。
- 若聚焦主题为空，则省略标识部分。

目标路径——选择与运行环境匹配的第一个目录：

Host	Base directory
Claude Code	`~/.claude/projects/<encoded-cwd>/handoff/`
Codex	`~/.codex/projects/<encoded-cwd>/handoff/`
OpenCode	`${XDG_CONFIG_HOME:-~/.config}/opencode/projects/<encoded-cwd>/handoff/`
pi	`~/.pi/agent/projects/<encoded-cwd>/handoff/`
Unknown	`.tmp/handoff/` in the current project

若无法确定运行环境，优先选择项目本地的

.tmp/handoff/

路径，而非猜测主目录——用户找不到的交接文档比存放在仓库中的文档更无用。

若不存在
```
handoff/
```
目录则创建。
若文件名冲突，则在
```
.md
```
前添加
```
-2
```
、
```
-3
```
等后缀。
将与内嵌模式相同的Markdown内容写入文件。
在聊天中仅输出以下两行内容，无其他信息：
```
[<filename>](<absolute-path>)
Read @<absolute-path> and continue the work.
```
第一行在支持的环境中会渲染为可点击链接；第二行是用于开启下一轮会话的复制粘贴快捷指令。

Gathering data

数据收集

Use only what the in-context conversation already provides plus light, read-only inspection if needed:

```
git rev-parse --abbrev-ref HEAD
```
— current branch.
```
git status --short
```
— working-tree state.
```
git log -1 --oneline
```
— last commit.
```
basename "$PWD"
```
— project name for the strap line.

Do not run mutating commands, do not edit code, do not commit. Reading project files to ground a fact is fine, but only if the conversation pointed at them — don't go exploring.

仅使用上下文对话中已有的信息，必要时可进行轻度只读检查：

```
git rev-parse --abbrev-ref HEAD
```
— 获取当前分支。
```
git status --short
```
— 获取工作区状态。
```
git log -1 --oneline
```
— 获取最后一次提交记录。
```
basename "$PWD"
```
— 获取项目名称用于标题行。

不得执行会修改数据的命令，不得编辑代码或提交。若对话中提及某些项目文件，可读取这些文件以验证事实，但不得主动探索未提及的文件。

Edge cases

边缘场景

Empty session / nothing substantive happened — exit with one line:

Nothing worth handing off from this session. No file, no Markdown body.
Compacted session — early turns may be invisible. Note this once under Goal or in a one-line aside if it materially affects the handoff.
Focus argument unrelated to actual session work — trust the focus as the user's framing for the next session, even if the previous session drifted. Slant the handoff toward continuing in the focus direction.
Multiple intermixed threads in the session — pick the one the focus points at; if no focus, pick the thread the user spent the most recent turns on. Mention dropped threads under Open questions only if they're load-bearing.

空会话/无实质性内容：输出以下一行内容后结束：

Nothing worth handing off from this session. 不生成文件，无Markdown内容。
压缩会话：早期对话内容可能不可见。若该情况对交接文档有实质性影响，需在“目标”章节中添加一行说明或单独用一行备注。
聚焦主题与实际会话内容无关：即使上一轮会话偏离主题，仍需将聚焦主题视为用户对下一轮会话的定位，调整交接文档内容以贴合聚焦主题的方向。
会话中包含多个交织线程：优先选择聚焦主题指向的线程；若无聚焦主题，则选择用户最近参与的线程。仅当被忽略的线程是关键内容时，才在“未解决问题”章节中提及。