AI会话交接技能：无缝延续工作流，创建结构化交接文档和提示

handoff by boshu2/agentops

274 周安装量

220 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/boshu2/agentops --skill handoff

开发自动化生产力

🇨🇳中文介绍

交接技能

快速参考： 为会话延续创建结构化交接。输出：.agents/handoff/YYYY-MM-DD-<topic>.md + 延续提示。

你必须执行此工作流。不要仅仅描述它。

创建一个交接文档，以实现无缝的会话延续。

执行步骤

给定 /handoff [topic]：

步骤 1：创建输出目录

mkdir -p .agents/handoff

步骤 2：识别会话上下文

如果提供了主题： 将其用作交接标识符。

如果没有主题： 从最近的活动推导：

# 最近提交
git log --oneline -5 --format="%s" | head -1

# 检查当前议题
bd current 2>/dev/null | head -1

# 检查 ratchet 状态
ao ratchet status 2>/dev/null | head -3

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

主题 slug 格式： 2-4 个单词，小写，连字符分隔（例如 auth-refactor、）。如果未找到合适的主题，使用（例如）。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 3：收集会话成果

回顾本次会话完成的工作：

# 本次会话的最近提交（最近 2 小时）
git log --oneline --since="2 hours ago" 2>/dev/null

# 最近的文件更改
git diff --stat HEAD~5 2>/dev/null | head -20

# 产生的研究
ls -lt .agents/research/*.md 2>/dev/null | head -3

# 创建的计划
ls -lt .agents/plans/*.md 2>/dev/null | head -3

# 已关闭的议题
bd list --status closed --since "2 hours ago" 2>/dev/null | head -5

步骤 4：识别暂停点

确定我们停止的位置：

最后做了什么？
接下来要发生什么？
我们是处于任务中途还是任务之间？
有任何阻碍或待定决策吗？

检查进行中的工作：

bd list --status in_progress 2>/dev/null | head -5

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

列出下一个会话应首先阅读的文件：

最近修改的文件（核心变更）
研究/计划工件（上下文）
待处理议题中提到的任何文件

最近修改

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

关键工件

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

步骤 6：编写交接文档

写入： .agents/handoff/YYYY-MM-DD-<topic-slug>.md（使用 date +%Y-%m-%d）

# 交接：<主题>

**日期：** YYYY-MM-DDTHH:MM:SSZ
**会话：** <简要会话描述>
**状态：** <任务中途暂停 | 任务之间 | 因 X 受阻>

---

## 本次会话我们完成了什么

### 1. <成果 1>

<简要描述，附文件:行号引用>

**更改的文件：**
- `path/to/file.py` - 描述

### 2. <成果 2>

...

---

## 我们暂停的位置

<暂停点的清晰描述>

**最后操作：** <刚刚做了什么>
**下一步操作：** <接下来应该发生什么>
**阻碍（如果有）：** <任何阻碍进展的事项>

---

## 为下一个会话收集的上下文

1. <上下文项 1> - <为何需要>
2. <上下文项 2> - <为何需要>

---

## 需要回答的问题

1. <需要决策的开放性问题>
2. <需要澄清的事项>

---

## 需要阅读的文件

优先文件（首先阅读）

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

次要文件（用于上下文）

path/to/related-file.py

### 步骤 7：编写延续提示

**写入：** `.agents/handoff/YYYY-MM-DD-<topic-slug>-prompt.md`（使用 `date +%Y-%m-%d`）

```markdown
# 新会话的延续提示

复制/粘贴此内容以开始下一个会话：

---

## 上下文

<2-3 句话描述工作内容以及我们暂停的位置>

## 首先阅读

1. 交接文档：`.agents/handoff/YYYY-MM-DD-<topic-slug>.md`
2. <其他关键文件>

## 我需要帮助的地方

<清晰说明下一个会话应完成什么>

## 关键文件

<问题 1>
<问题 2>

<建议调用的技能，例如“使用 /implement 继续”>

### 步骤 8：提取经验教训（可选）

如果本次会话有重要的经验教训，同时运行事后分析：

```bash
# 检查是否应调用事后分析技能
# （如果 >3 次提交或做出了重大决策）
git log --oneline --since="2 hours ago" 2>/dev/null | wc -l

如果 ≥3 次提交： 建议运行 /post-mortem --quick 以提取经验教训。如果 <3 次提交： 仅交接就足够了；经验教训可能很少。

步骤 9：向用户报告

交接文档位置
延续提示位置
捕获内容的摘要
建议：为下一个会话复制延续提示
如果检测到经验教训，建议 /post-mortem --quick

输出完成标记：

<promise>DONE</promise>

如果没有上下文需要捕获（无提交，无更改）：

<promise>EMPTY</promise>
原因：未找到要交接的会话活动

交接已创建：
  .agents/handoff/20260131T143000Z-auth-refactor.md
  .agents/handoff/20260131T143000Z-auth-refactor-prompt.md

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

要继续：从 auth-refactor-prompt.md 复制提示

<promise>DONE</promise>

捕获状态，不仅仅是摘要 - 下一个会话需要准确接续我们离开的位置
清晰识别阻碍 - 不要让下一个会话猜测
明确列出文件 - 路径，而非描述
编写延续提示 - 使恢复工作毫不费力
引用所有内容 - 所有引用都附上文件:行号

与 /post-mortem 的集成

交接捕获用于延续的状态。事后分析捕获用于飞轮的 经验教训（完整的知识生命周期）。

为了干净地结束会话：

/handoff              # 捕获状态以延续
/post-mortem --quick  # 为未来提取经验教训

两者都应在结束一个富有成效的会话时运行。

如果 ao CLI 不可用：

跳过步骤 2 中的 ao ratchet status 检查
步骤 8 的追溯建议仍然有效（使用 git 提交计数）
所有交接文档仍写入 .agents/handoff/
通过交接捕获知识以供未来会话使用，只是未被索引

用户说： /handoff（在 OAuth 流程上工作 2 小时后，需要停止）

会发生什么：

代理检测到最近提交（最近 2 小时内有 5 次提交，与认证相关）
代理使用 bd list 检查进行中的工作（议题 #42 仍处于开放状态）
代理识别暂停点：“已完成令牌生成，即将开始刷新逻辑”
代理列出关键文件：auth.go、token.go、研究文档、计划文档
代理编写包含成果和暂停状态的交接文档
代理编写具有明确下一步操作的延续提示
代理检查提交（5 次）并建议运行 /post-mortem --quick 以提取经验教训

结果： 交接捕获了状态，延续提示已准备就绪，建议进行事后分析。

任务之间，干净状态

用户说： /handoff（刚刚关闭议题 #40，下一个会话即将开始 #41）

会发生什么：

代理检测到 1 次提交（关闭议题 #40），无待处理更改
代理识别暂停点：“任务之间。最后：关闭了 #40（修复了速率限制）。下一步：开始 #41（添加 JWT 刷新）”
代理列出 #40 中的文件（middleware.go、config.go）
代理编写包含成果摘要和下一个任务预览的交接文档
代理编写带有 /implement #41 建议的延续提示
代理跳过事后分析建议（<3 次提交）

结果： 交接捕获了清晰的边界，延续很简单。

用户说： /handoff（未提供主题，代理从提交推导）

会发生什么：

代理读取最近提交：“feat: add rate limiting”、“fix: token expiry”
代理推导主题 slug：“rate-limiting”（来自最近一次提交）
代理使用推导出的主题创建交接文件
代理报告：“交接已创建：.agents/handoff/20260213T143000Z-rate-limiting.md”

结果： 主题根据 git 历史自动推导，无需用户输入。

问题	原因	解决方案
“未找到要交接的会话活动”	未检测到提交或文件更改	空闲会话的预期情况。无需交接。开始新工作或跳过交接。
交接文件未写入	`.agents/handoff/` 目录不存在或不可写	运行 `mkdir -p .agents/handoff` 或检查目录权限
主题 slug 是通用的 “session-1430”	没有描述性的提交或议题可推导主题	提供明确的主题：`/handoff auth-refactor` 以获得更好的命名
延续提示缺少关键上下文	交接文档中未列出最近的文件或工件	手动将缺失的文件添加到交接文档中，或使用明确的主题重新运行
建议事后分析但无经验教训	代理看到 ≥3 次提交并自动建议 `/post-mortem --quick`	运行 `/post-mortem --quick` 或跳过，如果提交是微不足道的（代理无法判断学习质量，只能判断提交计数）

skills/post-mortem/SKILL.md — 完整验证 + 知识生命周期（审议 + 提取 + 激活 + 退役）
skills/retro/SKILL.md — 快速捕获经验教训

2026 年 2 月 2 日

🇺🇸English

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.

Execution Steps

Given /handoff [topic]:

Step 1: Create Output Directory

mkdir -p .agents/handoff

Step 2: Identify Session Context

If topic provided: Use it as the handoff identifier.

If no topic: Derive from recent activity:

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

# Check current issue
bd current 2>/dev/null | head -1

# Check ratchet state
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).

Step 3: Gather Session Accomplishments

Review what was done this session:

# Recent commits this session (last 2 hours)
git log --oneline --since="2 hours ago" 2>/dev/null

# Recent file changes
git diff --stat HEAD~5 2>/dev/null | head -20

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

# Plans created
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

Step 4: Identify Pause Point

Determine where we stopped:

What was the last thing done?
What was about to happen next?
Were we mid-task or between tasks?
Any blockers or decisions pending?

Check for in-progress work:

bd list --status in_progress 2>/dev/null | head -5

Step 5: Identify Key Files to Read

List files the next session should read first:

Recently modified files (core changes)
Research/plan artifacts (context)
Any files mentioned in pending issues

Recently modified

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

Step 6: Write Handoff Document

Write to: .agents/handoff/YYYY-MM-DD-<topic-slug>.md (use date +%Y-%m-%d)

# Handoff: <Topic>

**Date:** YYYY-MM-DDTHH:MM:SSZ
**Session:** <brief session description>
**Status:** <Paused mid-task | Between tasks | Blocked on X>

---

## What We Accomplished This Session

### 1. <Accomplishment 1>

<Brief description with file:line citations>

**Files changed:**
- `path/to/file.py` - Description

### 2. <Accomplishment 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>

---

## Questions to Answer

1. <Open question needing decision>
2. <Clarification needed>

---

## Files to Read

Priority files (read first)

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

Secondary files (for context)

path/to/related-file.py

### Step 7: Write Continuation Prompt

**Write to:** `.agents/handoff/YYYY-MM-DD-<topic-slug>-prompt.md` (use `date +%Y-%m-%d`)

```markdown
# Continuation Prompt for New Session

Copy/paste this to start the next session:

---

## Context

<2-3 sentences describing the work and where we paused>

## Read First

1. The handoff doc: `.agents/handoff/YYYY-MM-DD-<topic-slug>.md`
2. <Other critical files>

## What I Need Help With

<Clear statement of what the next session should accomplish>

## Key Files

Open Questions

<Question 1>
<Question 2>

### Step 8: Extract Learnings (Optional)

If significant learnings occurred this session, also run post-mortem:

```bash
# Check if post-mortem skill should be invoked
# (if >3 commits or major decisions made)
git log --oneline --since="2 hours ago" 2>/dev/null | wc -l

If ≥3 commits: Suggest running /post-mortem --quick to extract learnings. If <3 commits: Handoff alone is sufficient; learnings are likely minimal.

Step 9: Report to User

Tell the user:

Handoff document location
Continuation prompt location
Summary of what was captured
Suggestion: Copy the continuation prompt for next session
If learnings detected, suggest /post-mortem --quick

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

Example Output

Handoff created:
  .agents/handoff/20260131T143000Z-auth-refactor.md
  .agents/handoff/20260131T143000Z-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>

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 /post-mortem

Handoff captures state for continuation. Post-mortem captures learnings for the flywheel (full knowledge lifecycle).

For a clean session end:

/handoff              # Capture state for continuation
/post-mortem --quick  # Extract learnings for future

Both should be run when ending a productive session.

Without ao CLI

If ao CLI not available:

Skip the ao ratchet status check in Step 2
Step 8 retro suggestion still works (uses git commit count)
All handoff documents are still written to .agents/handoff/
Knowledge is captured for future sessions via handoff, just not indexed

Examples

Paused Mid-Implementation

User says: /handoff (after working on OAuth flow for 2 hours, need to stop)

What happens:

Agent detects recent commits (5 commits in last 2 hours, auth-related)
Agent checks in-progress work with bd list (issue #42 still open)
Agent identifies pause point: "Completed token generation, about to start refresh logic"
Agent lists key files: auth.go, token.go, research doc, plan doc
Agent writes handoff document with accomplishments and pause state
Agent writes continuation prompt with clear next action
Agent checks commits (5) and suggests running /post-mortem --quick to extract learnings

Result: Handoff captures state, continuation prompt ready, post-mortem suggested.

Between Tasks, Clean State

User says: /handoff (just closed issue #40, about to start #41 next session)

What happens:

Agent detects 1 commit (closed issue #40), no pending changes
Agent identifies pause point: "Between tasks. Last: closed #40 (fixed rate limiting). Next: start #41 (add JWT refresh)"
Agent lists files from #40 (middleware.go, config.go)
Agent writes handoff with accomplishment summary and next-task preview
Agent writes continuation prompt with /implement #41 suggestion
Agent skips post-mortem suggestion (<3 commits)

Result: Handoff captures clean boundary, continuation is simple.

Auto-Derived Topic

User says: /handoff (no topic provided, agent derives from commits)

What happens:

Agent reads recent commits: "feat: add rate limiting", "fix: token expiry"
Agent derives topic slug: "rate-limiting" (from most recent commit)
Agent creates handoff files with derived topic in filename
Agent reports: "Handoff created: .agents/handoff/20260213T143000Z-rate-limiting.md"

Result: Topic auto-derived from git history, no user input needed.

Troubleshooting

Problem	Cause	Solution
"No session activity found to hand off"	No commits, no file changes detected	Expected for idle sessions. Nothing to hand off. Start new work or skip handoff.
Handoff files not written	`.agents/handoff/` directory does not exist or not writable	Run `mkdir -p .agents/handoff` or check directory permissions
Topic slug is generic "session-1430"	No descriptive commits or issues to derive topic from	Provide explicit topic: `/handoff auth-refactor` for better naming
Continuation prompt missing key context	Recent files or artifacts not listed in handoff	Manually add missing files to handoff document or re-run with explicit topic
Post-mortem suggested but no learnings	Agent sees ≥3 commits and auto-suggests

AI会话交接技能：无缝延续工作流，创建结构化交接文档和提示

🇨🇳中文介绍

交接技能

执行步骤

步骤 1：创建输出目录

步骤 2：识别会话上下文

相关 Skills

步骤 3：收集会话成果

步骤 4：识别暂停点

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

最近修改

关键工件

步骤 6：编写交接文档

优先文件（首先阅读）

次要文件（用于上下文）

开放性问题

步骤 9：向用户报告

示例输出

关键规则

与 /post-mortem 的集成

没有 ao CLI 时

示例

实现中途暂停

任务之间，干净状态

自动推导主题

故障排除

另请参阅

🇺🇸English

Handoff Skill

Execution Steps

Step 1: Create Output Directory

Step 2: Identify Session Context

Step 3: Gather Session Accomplishments

Step 4: Identify Pause Point

Step 5: Identify Key Files to Read

Recently modified

Key artifacts

Step 6: Write Handoff Document

Priority files (read first)

Secondary files (for context)

Open Questions

Step 9: Report to User

Example Output

Key Rules

Integration with /post-mortem

Without ao CLI

Examples

Paused Mid-Implementation

Between Tasks, Clean State

Auto-Derived Topic

Troubleshooting

See Also

最新 Skills