什么是 会话移交？

会话移交是一个关键工具，旨在解决长期运行的 AI 开发会话中上下文窗口枯竭的持久问题。通过生成结构化、经过验证的移交文档，此技能可确保任何新代理都能从上一个代理停止的地方继续工作，并保持对技术决策、当前状态和紧要任务的充分了解。它是 Openclaw Skills 库中管理大规模工程项目的重要组成部分。

此技能为保存和恢复工作提供了正式协议。无论您是达到 Token 限制、在模型之间切换，还是暂停当天的任务，会话移交都能捕捉到如果不这样做就会丢失的细微决策理由和环境状态。通过将其集成到您的工作流中，您可以利用 Openclaw Skills 的全部功能，跨碎片的聊天会话保持连续性。

下载入口:https://github.com/openclaw/skills/tree/main/skills/wpank/session-handoff

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

会话移交 应用场景

• 在 AI 代理的上下文窗口达到最大容量时保存项目状态。
• 在不同的 AI 模型或代理实例之间过渡复杂的开发任务。
• 在重大里程碑期间创建架构决策和技术理由的永久记录。
• 在长时间停顿或上下文切换后恢复深度专注的工作。
• 管理跨越数天或涉及数十个文件编辑的长期功能开发。

1. 当上下文已满或达到里程碑时，用户使用 Openclaw Skills 识别的关键词触发流程。
2. 执行智能支架脚本，自动捕获环境元数据，如 git 分支、最近的提交和修改的文件。
3. 代理或用户完成移交文档，填写“紧要后续步骤”和“已做出的决策”等关键部分。
4. 验证脚本审查文档质量，检查缺失部分，并扫描意外泄露的机密信息或 API 密钥。
5. 恢复时，系统会检查陈旧性，以确保移交内容仍与代码库的当前状态匹配。
6. 新代理加载移交链，识别第一个操作项，并在恢复完整上下文的情况下开始工作。

会话移交 配置指南

要在您的 Openclaw Skills 环境中实现会话移交，请利用项目脚本目录中提供的 Python 实用脚本。

# 为特定任务生成新的移交支架
python scripts/create_handoff.py [task-slug]

# 在关闭会话前验证移交文档的质量和安全性
python scripts/validate_handoff.py .claude/handoffs/YYYY-MM-DD-slug.md

# 列出并检查现有移交文件的状态
python scripts/list_handoffs.py

会话移交 数据架构与分类体系

会话移交使用带时间戳的命名约定将数据存储在 .claude/handoffs/ 的结构化目录中。这确保了 Openclaw Skills 生态系统内清晰的进度历史。

name: session-handoff
model: standard
description: |
  WHAT: Create comprehensive handoff documents that enable fresh AI agents to seamlessly continue work with zero ambiguity. Solves long-running agent context exhaustion problem.
  
  WHEN: (1) User requests handoff/memory/context save, (2) Context window approaches capacity, (3) Major task milestone completed, (4) Work session ending, (5) Resuming work with existing handoff.
  
  KEYWORDS: "save state", "create handoff", "context is full", "I need to pause", "resume from", "continue where we left off", "load handoff", "save progress", "session transfer", "hand off"

Session Handoff

Create handoff documents that enable fresh agents to continue work seamlessly.

Mode Selection

Creating a handoff? User wants to save state, pause work, or context is full. → Follow CREATE Workflow

Resuming from a handoff? User wants to continue previous work or load context. → Follow RESUME Workflow

Proactive suggestion? After substantial work (5+ file edits, complex debugging, major decisions):

"Consider creating a handoff document to preserve this context. Say 'create handoff' when ready."

CREATE Workflow

Step 1: Generate Scaffold

Run the smart scaffold script:

python scripts/create_handoff.py [task-slug]

For continuation handoffs (linking to previous work):

python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md

The script creates .claude/handoffs/ directory and generates a timestamped file with pre-filled metadata (timestamp, project path, git branch, recent commits, modified files).

Step 2: Complete the Document

Open the generated file and fill all [TODO: ...] sections. Prioritize:

1. Current State Summary - What's happening right now
2. Important Context - Critical info the next agent MUST know
3. Immediate Next Steps - Clear, actionable first steps
4. Decisions Made - Choices with rationale (not just outcomes)

See references/handoff-template.md for full structure.

Step 3: Validate

python scripts/validate_handoff.py 

Checks:

• No [TODO: ...] placeholders remaining
• Required sections present and populated
• No potential secrets detected (API keys, passwords, tokens)
• Referenced files exist
• Quality score (0-100)

Do not finalize handoffs with secrets detected or score below 70.

Step 4: Confirm

Report to user:

• Handoff file location
• Validation score and warnings
• Summary of captured context
• First action item for next session

RESUME Workflow

Step 1: Find Handoffs

python scripts/list_handoffs.py

Step 2: Check Staleness

python scripts/check_staleness.py 

Staleness levels:

• FRESH: Safe to resume
• SLIGHTLY_STALE: Review changes first
• STALE: Verify context carefully
• VERY_STALE: Consider creating fresh handoff

Step 3: Load and Verify

Read the handoff document completely. If part of a chain, also read the previous handoff.

Follow references/resume-checklist.md:

1. Verify project directory and git branch match
2. Check if blockers resolved
3. Validate assumptions still hold
4. Review modified files for conflicts

Step 4: Begin Work

Start with "Immediate Next Steps" item #1.

Reference as you work:

• "Critical Files" for important locations
• "Key Patterns Discovered" for conventions
• "Potential Gotchas" to avoid known issues

Handoff Chaining

For long-running projects, chain handoffs to maintain context lineage:

handoff-1.md (initial work)
    ↓
handoff-2.md --continues-from handoff-1.md
    ↓
handoff-3.md --continues-from handoff-2.md

When resuming from a chain, read the most recent handoff first, then reference predecessors as needed.

Storage

Location: .claude/handoffs/ Naming: YYYY-MM-DD-HHMMSS-[slug].md

Quality Criteria

Good handoffs have:

• Zero ambiguity about current state
• Clear, numbered next steps
• Rationale for decisions (not just outcomes)
• File paths with line numbers where relevant
• No secrets or credentials

NEVER

• Include API keys, passwords, tokens, or credentials
• Leave TODO placeholders in finalized handoffs
• Skip the validation step
• Create handoffs without the Important Context section
• Finalize handoffs with quality score below 70