Back to Details

handoff

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Handoff Skill

Handoff Skill

Quick Ref: Create structured handoff for session continuation. Output: 
.agents/handoff/YYYY-MM-DD-<topic>.md
+ continuation prompt.
YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.
Create a handoff document that enables seamless session continuation.
快速参考： 为会话续接创建结构化的交接机制。输出：
.agents/handoff/YYYY-MM-DD-<topic>.md
+ 续接提示词。
你必须执行此工作流，而非仅进行描述。
创建一份交接文档，实现无缝的会话续接。

Execution Steps

执行步骤

Given 
/handoff [topic]
:
当输入 
/handoff [topic]
时：

Step 1: Create Output Directory

步骤1：创建输出目录

bash
mkdir -p .agents/handoff
bash
mkdir -p .agents/handoff

Step 2: Identify Session Context

步骤2：识别会话上下文

If topic provided: Use it as the handoff identifier.
If no topic: Derive from recent activity:
bash
undefined
若提供了主题： 将其用作交接标识符。
若未提供主题： 从近期活动中推导：
bash
undefined

Recent commits

近期提交记录

git log --oneline -5 --format="%s" | head -1
git log --oneline -5 --format="%s" | head -1

Check current issue

查看当前工单

bd current 2>/dev/null | head -1
bd current 2>/dev/null | head -1

Check ratchet state

查看ratchet状态

ao ratchet status 2>/dev/null | head -3

Use the most descriptive source as the topic slug.

**Topic slug format:** 2-4 words, lowercase, hyphen-separated (e.g., `auth-refactor`, `api-validation`).
**Fallback:** If no good topic found, use `session-$(date +%H%M)` (e.g., `session-1430`).
ao ratchet status 2>/dev/null | head -3

使用最具描述性的来源作为主题别名。

**主题别名格式：** 2-4个单词，小写，用连字符分隔（例如：`auth-refactor`, `api-validation`）。
**备选方案：** 若未找到合适的主题，使用 `session-$(date +%H%M)`（例如：`session-1430`）。

Step 3: Gather Session Accomplishments

步骤3：汇总会话成果

Review what was done this session:
bash
undefined
回顾本次会话完成的工作：
bash
undefined

Recent commits this session (last 2 hours)

本次会话的近期提交记录（过去2小时）

git log --oneline --since="2 hours ago" 2>/dev/null
git log --oneline --since="2 hours ago" 2>/dev/null

Recent file changes

近期文件变更

git diff --stat HEAD~5 2>/dev/null | head -20
git diff --stat HEAD~5 2>/dev/null | head -20

Research produced

生成的研究文档

ls -lt .agents/research/*.md 2>/dev/null | head -3
ls -lt .agents/research/*.md 2>/dev/null | head -3

Plans created

创建的计划文档

ls -lt .agents/plans/*.md 2>/dev/null | head -3
ls -lt .agents/plans/*.md 2>/dev/null | head -3

Issues closed

已关闭的工单

bd list --status closed --since "2 hours ago" 2>/dev/null | head -5
undefined
bd list --status closed --since "2 hours ago" 2>/dev/null | head -5
undefined

Step 4: Identify Pause Point

步骤4：确定暂停节点

Determine where we stopped:
  1. What was the last thing done?
  2. What was about to happen next?
  3. Were we mid-task or between tasks?
  4. Any blockers or decisions pending?
Check for in-progress work:
bash
bd list --status in_progress 2>/dev/null | head -5
明确我们的工作停止位置：
  1. 最后完成的工作是什么？
  2. 接下来原本要进行什么操作？
  3. 我们处于任务进行中还是任务间隙？
  4. 是否存在阻碍或待决策事项？
检查进行中的工作：
bash
bd list --status in_progress 2>/dev/null | head -5

Step 5: Identify Key Files to Read

步骤5：识别需优先阅读的关键文件

List files the next session should read first:
  • Recently modified files (core changes)
  • Research/plan artifacts (context)
  • Any files mentioned in pending issues
bash
undefined
列出下一次会话应首先阅读的文件：
  • 近期修改的文件（核心变更）
  • 研究/计划类文档（上下文信息）
  • 待处理工单中提及的任何文件
bash
undefined

Recently modified

近期修改的文件

git diff --name-only HEAD~5 2>/dev/null | head -10
git diff --name-only HEAD~5 2>/dev/null | head -10

Key artifacts

关键文档

ls .agents/research/.md .agents/plans/.md 2>/dev/null | tail -5
undefined
ls .agents/research/.md .agents/plans/.md 2>/dev/null | tail -5
undefined

Step 6: Write Handoff Document

步骤6：编写交接文档

Write to: 
.agents/handoff/YYYY-MM-DD-<topic-slug>.md
markdown
undefined
写入路径： 
.agents/handoff/YYYY-MM-DD-<topic-slug>.md
markdown
undefined

Handoff: <Topic>

Handoff: <Topic>

Date: YYYY-MM-DD Session: <brief session description> Status: <Paused mid-task | Between tasks | Blocked on X>
日期： YYYY-MM-DD 会话： <简短的会话描述> 状态： <任务进行中暂停 | 任务间隙 | 因X事项受阻>

What We Accomplished This Session

本次会话完成的成果

1. <Accomplishment 1>

1. <成果1>

<Brief description with file:line citations>
Files changed:
  • path/to/file.py
    - Description
<带文件:行号引用的简短描述>
修改的文件：
  • path/to/file.py
    - 描述

2. <Accomplishment 2>

2. <成果2>

...
...

Where We Paused

暂停位置

<Clear description of pause point>
Last action: <what was just done> Next action: <what should happen next> Blockers (if any): <anything blocking progress>
<清晰描述暂停节点>
最后操作： <刚完成的工作> 下一步操作： <接下来应进行的工作> 阻碍事项（若有）： <任何影响进度的事项>

Context to Gather for Next Session

下一次会话需收集的上下文

  1. <Context item 1> - <why needed>
  2. <Context item 2> - <why needed>
  1. <上下文项1> - <需求原因>
  2. <上下文项2> - <需求原因>

Questions to Answer

待解答的问题

  1. <Open question needing decision>
  2. <Clarification needed>
  1. <待决策的开放性问题>
  2. <需澄清的问题>

Files to Read

需阅读的文件

undefined
undefined

Priority files (read first)

优先级文件（优先阅读）

path/to/critical-file.py .agents/research/YYYY-MM-DD-topic.md
path/to/critical-file.py .agents/research/YYYY-MM-DD-topic.md

Secondary files (for context)

次要文件（用于补充上下文）

path/to/related-file.py
undefined
path/to/related-file.py
undefined

Step 7: Write Continuation Prompt

步骤7：编写续接提示词

Write to: 
.agents/handoff/YYYY-MM-DD-<topic-slug>-prompt.md
markdown
undefined
写入路径： 
.agents/handoff/YYYY-MM-DD-<topic-slug>-prompt.md
markdown
undefined

Continuation Prompt for New Session

新会话续接提示词

Copy/paste this to start the next session:
复制粘贴以下内容以启动下一次会话：

Context

上下文

<2-3 sentences describing the work and where we paused>
<2-3句话描述工作内容及暂停位置>

Read First

优先阅读

  1. The handoff doc: 
    .agents/handoff/YYYY-MM-DD-<topic-slug>.md
  2. <Other critical files>
  1. 交接文档：
    .agents/handoff/YYYY-MM-DD-<topic-slug>.md
  2. <其他关键文件>

What I Need Help With

我需要的帮助

<Clear statement of what the next session should accomplish>
<清晰说明下一次会话应完成的工作>

Key Files

关键文件

<list of paths to read>
<需阅读的路径列表>

Open Questions

开放性问题

  1. <Question 1>
  2. <Question 2>
<Suggested skill to invoke, e.g., "Use /implement to continue">
undefined
  1. <问题1>
  2. <问题2>
<建议调用的Skill，例如："使用 /implement 继续">
undefined

Step 8: Extract Learnings (Optional)

步骤8：提取经验总结（可选）

If significant learnings occurred this session, also run retro:
bash
undefined
若本次会话产生了重要经验，同时运行retro：
bash
undefined

Check if retro skill should be invoked

检查是否应调用retro skill

(if >3 commits or major decisions made)

（若提交次数>3或做出重大决策）

git log --oneline --since="2 hours ago" 2>/dev/null | wc -l

**If ≥3 commits:** Suggest running `/retro` to extract learnings.
**If <3 commits:** Handoff alone is sufficient; learnings are likely minimal.
git log --oneline --since="2 hours ago" 2>/dev/null | wc -l

**若提交次数≥3：** 建议运行 `/retro` 提取经验总结。
**若提交次数<3：** 仅完成交接即可；经验总结可能较少。

Step 9: Report to User

步骤9：向用户反馈

Tell the user:
  1. Handoff document location
  2. Continuation prompt location
  3. Summary of what was captured
  4. Suggestion: Copy the continuation prompt for next session
  5. If learnings detected, suggest 
    /retro
Output completion marker:
<promise>DONE</promise>
If no context to capture (no commits, no changes):
<promise>EMPTY</promise>
Reason: No session activity found to hand off
告知用户：
  1. 交接文档的位置
  2. 续接提示词的位置
  3. 已捕获内容的摘要
  4. 建议：复制续接提示词用于下一次会话
  5. 若检测到可总结的经验，建议运行 
    /retro
输出完成标记：
<promise>DONE</promise>
若无可捕获的上下文（无提交、无变更）：
<promise>EMPTY</promise>
Reason: No session activity found to hand off

Example Output

示例输出

Handoff created:
  .agents/handoff/2026-01-31-auth-refactor.md
  .agents/handoff/2026-01-31-auth-refactor-prompt.md

Session captured:
- 5 commits, 12 files changed
- Paused: mid-implementation of OAuth flow
- Next: Complete token refresh logic

To continue: Copy the prompt from auth-refactor-prompt.md

<promise>DONE</promise>
交接文档已创建：
  .agents/handoff/2026-01-31-auth-refactor.md
  .agents/handoff/2026-01-31-auth-refactor-prompt.md

会话内容已捕获：
- 5次提交，12个文件变更
- 暂停状态：OAuth流程实现中
- 下一步：完成令牌刷新逻辑

续接方式：复制auth-refactor-prompt.md中的提示词

<promise>DONE</promise>

Key Rules

核心规则

  • Capture state, not just summary - next session needs to pick up exactly where we left off
  • Identify blockers clearly - don't leave the next session guessing
  • List files explicitly - paths, not descriptions
  • Write the continuation prompt - make resumption effortless
  • Cite everything - file:line for all references
  • 捕获状态，而非仅摘要 - 下一次会话需要精准接续工作
  • 明确识别阻碍事项 - 不要让下一次会话猜测问题
  • 明确列出文件 - 提供路径，而非仅描述
  • 编写续接提示词 - 让续接工作更轻松
  • 所有内容需标注引用 - 所有参考均需包含文件:行号

Integration with /retro

与/retro的集成

Handoff captures state for continuation. Retro captures learnings for the flywheel.
For a clean session end:
bash
/handoff  # Capture state for continuation
/retro    # Extract learnings for future
Both should be run when ending a productive session.
Handoff捕获状态以实现续接。 Retro提取经验总结以优化后续工作。
结束高效会话时，应同时运行：
bash
/handoff  # 捕获状态用于续接
/retro    # 提取经验总结用于未来工作
在结束富有成效的会话时，两者都应运行。

Without ao CLI

无ao CLI时的处理

If ao CLI not available:
  1. Skip the 
    ao ratchet status
    check in Step 2
  2. Step 8 retro suggestion still works (uses git commit count)
  3. All handoff documents are still written to 
    .agents/handoff/
  4. Knowledge is captured for future sessions via handoff, just not indexed
若ao CLI不可用：
  1. 跳过步骤2中的
    ao ratchet status
    检查
  2. 步骤8中的retro建议仍然有效（使用git提交次数判断）
  3. 所有交接文档仍将写入
    .agents/handoff/
  4. 知识将通过交接文档捕获以供未来会话使用，只是不会被索引