agent-handoff

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Handoff — Bootstrapper & Manager

Agent Handoff — 初始化器与管理器

This skill bootstraps and maintains the

.ai/

shared context directory that enables seamless handoff between AI agents (Claude, Codex, Gemini, Cursor, Windsurf, OpenCode, Copilot, and others).

The always-active read/write behavior is handled by the snippet injected into each agent's config file (CLAUDE.md, codex.md, .cursorrules, etc.) during installation. This skill handles the heavier operations: first-run bootstrapping, stale detection, and project scanning.

For file format templates, see

references/templates.md

. For real-world examples, see

references/examples.md

此 skill 初始化并维护

.ai/

共享上下文目录，使 Claude、Codex、Gemini、Cursor、Windsurf、OpenCode、Copilot 等 AI Agent 之间能够无缝交接。

安装期间注入各 Agent 配置文件的代码片段负责处理始终启用的读/写行为。本 skill 负责更繁重的操作：首次运行初始化、过期检测和项目扫描。

文件格式模板见

references/templates.md

。实际案例见

references/examples.md

。

When This Skill Triggers

此 Skill 的触发条件

User says "agent handoff", "handoff", "bootstrap", "initialize", "set up handoff", "set up agent context"
User says "continue", "resume", "keep going", "what was the last agent doing"
Any core
```
.ai/
```
file is missing, empty, or still has installer placeholders:
```
.ai/PROJECT.md
```
,
```
.ai/PATHS.md
```
,
```
.ai/PLAN.md
```
,
```
.ai/conversations/HANDOFF.md
```
HANDOFF.md is stale (>7 days since last update)
User asks about session files, missing handoff writes, or another agent not invoking the handoff flow
User explicitly invokes
```
/agent-handoff
```

用户说“Agent handoff”“handoff”“初始化”“设置 handoff”“设置 Agent 上下文”
用户说“继续”“恢复”“继续进行”“上一个 Agent 在做什么”
任一核心
```
.ai/
```
文件缺失、为空，或仍包含安装器占位符：
```
.ai/PROJECT.md
```
、
```
.ai/PATHS.md
```
、
```
.ai/PLAN.md
```
、
```
.ai/conversations/HANDOFF.md
```
HANDOFF.md 已过期（距上次更新超过 7 天）
用户询问 session 文件、缺失的 handoff 写入，或另一个 Agent 未调用 handoff 流程
用户显式调用
```
/agent-handoff
```

First-Run Bootstrapping

首次运行初始化

Run the full bootstrap if any required file is missing, empty, or placeholder-only:

```
.ai/PROJECT.md
```
```
.ai/PATHS.md
```
```
.ai/PLAN.md
```
```
.ai/conversations/HANDOFF.md
```

Placeholder examples include

Last updated: —

(empty)

, "created (empty, will be populated on first agent run)", or files with only a heading.

如果任何必需文件缺失、为空或仅含占位符，则运行完整的初始化流程：

```
.ai/PROJECT.md
```
```
.ai/PATHS.md
```
```
.ai/PLAN.md
```
```
.ai/conversations/HANDOFF.md
```

占位符示例包括

Last updated: —

、

(empty)

、"created (empty, will be populated on first agent run)"，或只有标题的文件。

Step 1: Create directory structure

第 1 步：创建目录结构

bash

mkdir -p .ai/conversations/decisions .ai/conversations/sessions
mkdir -p ".ai/conversations/sessions/$(date +%F)"

bash

mkdir -p .ai/conversations/decisions .ai/conversations/sessions
mkdir -p ".ai/conversations/sessions/$(date +%F)"

Step 2: Detect project type and tech stack

第 2 步：检测项目类型和技术栈

Read all package manifests that exist (a polyglot project may have several):

```
composer.json
```
— PHP (Laravel, Symfony, etc.)
```
package.json
```
— Node.js / frontend (Next.js, Nuxt, React, Vue, Angular, etc.)
```
Gemfile
```
— Ruby (Rails, Sinatra, etc.)
```
requirements.txt
```
/
```
pyproject.toml
```
/
```
Pipfile
```
— Python (Django, Flask, FastAPI, etc.)
```
go.mod
```
— Go
```
Cargo.toml
```
— Rust
```
pom.xml
```
/
```
build.gradle
```
— Java / Kotlin
```
*.csproj
```
/
```
*.sln
```
— .NET

Read all agent/convention configs that exist:

CLAUDE.md

AGENTS.md

.cursorrules

.windsurfrules

codex.md

GEMINI.md

```
README.md
```
,
```
CONTRIBUTING.md
```

.editorconfig

, lint configs (

.prettierrc

eslint.config.*

phpcs.xml

, etc.)

Read environment hints:

```
.env.example
```
— expected environment variables
```
docker-compose.yml
```
/
```
Dockerfile
```
— containerized setup
```
Makefile
```
/
```
justfile
```
— common commands

读取所有已存在的包清单文件（多语言项目可能不止一个）：

```
composer.json
```
— PHP（Laravel、Symfony 等）
```
package.json
```
— Node.js / 前端（Next.js、Nuxt、React、Vue、Angular 等）
```
Gemfile
```
— Ruby（Rails、Sinatra 等）
```
requirements.txt
```
/
```
pyproject.toml
```
/
```
Pipfile
```
— Python（Django、Flask、FastAPI 等）
```
go.mod
```
— Go
```
Cargo.toml
```
— Rust
```
pom.xml
```
/
```
build.gradle
```
— Java / Kotlin
```
*.csproj
```
/
```
*.sln
```
— .NET

读取所有存在的 Agent/约定配置：

CLAUDE.md

、

AGENTS.md

、

.cursorrules

、

.windsurfrules

、

codex.md

、

GEMINI.md

```
README.md
```
、
```
CONTRIBUTING.md
```

.editorconfig

、lint 配置（

.prettierrc

、

eslint.config.*

、

phpcs.xml

等）

读取环境提示信息：

```
.env.example
```
— 预期的环境变量
```
docker-compose.yml
```
/
```
Dockerfile
```
— 容器化环境设置
```
Makefile
```
/
```
justfile
```
— 常用命令

Step 3: Discover documentation

第 3 步：发现文档

Scan these locations for documentation files:

Root:        *.md files (README, CHANGELOG, CONTRIBUTING, ARCHITECTURE, etc.)
Docs:        docs/  documentation/  wiki/  guides/  .github/
Specs:       specs/  spec/  plans/  rfcs/  adrs/  design/  proposals/
API:         docs/api/  api-docs/
             openapi.yaml  openapi.json  swagger.json  swagger.yaml
             *.postman_collection.json (up to 3 levels deep)
             insomnia*.json  insomnia*.yaml
Nested:      docs/archive/  docs/plans/  any docs/ subdirectory with markdown

For each location found:

bash

find {dir} -maxdepth 3 -type f \( -name "*.md" -o -name "*.pdf" -o -name "*.postman_collection.json" -o -name "openapi.*" -o -name "swagger.*" \)

Classify by reading the title or first 10 lines:

Category	Examples	Priority
Requirements	TRD, PRD, BRD	HIGH — read before implementing
Architecture	System design, ADR	HIGH
Implementation Plans	Roadmap, phasing doc	HIGH
Project Overview	Overview, project brief	HIGH
Operational Guides	User guides, runbooks	MEDIUM
API Documentation	Integration guides, OpenAPI	MEDIUM
Feature Specs	Per-feature specs, RFCs	ON-DEMAND
Archived	Anything in archive/ or older version	LOW

Version detection: When multiple versions exist (e.g., TRD-v3, TRD-v4, TRD-v5), identify the current version by highest number or most recent date. List only the current version under "Reference Documents (current)." Older versions go to "Archived."

扫描以下位置以查找文档文件：

Root:        *.md files (README, CHANGELOG, CONTRIBUTING, ARCHITECTURE, etc.)
Docs:        docs/  documentation/  wiki/  guides/  .github/
Specs:       specs/  spec/  plans/  rfcs/  adrs/  design/  proposals/
API:         docs/api/  api-docs/
             openapi.yaml  openapi.json  swagger.json  swagger.yaml
             *.postman_collection.json (up to 3 levels deep)
             insomnia*.json  insomnia*.yaml
Nested:      docs/archive/  docs/plans/  any docs/ subdirectory with markdown

对于找到的每个位置：

bash

find {dir} -maxdepth 3 -type f \( -name "*.md" -o -name "*.pdf" -o -name "*.postman_collection.json" -o -name "openapi.*" -o -name "swagger.*" \)

通过阅读标题或前 10 行进行分类：

类别	示例	优先级
需求	TRD、PRD、BRD	高——实现前阅读
架构	系统设计、ADR	高
实施计划	Roadmap、分阶段文档	高
项目概览	概览、项目简介	高
操作指南	用户指南、runbook	中
API 文档	集成指南、OpenAPI	中
功能规格	各功能的规格、RFC	按需
已归档	archive/ 中的内容或旧版本	低

**版本检测：**当存在多个版本时（例如 TRD-v3、TRD-v4、TRD-v5），通过最高版本号或最近日期确定当前版本。仅将当前版本列在“Reference Documents (current)”下。旧版本归入“Archived”。

Step 4: Detect spec/plan directory patterns

第 4 步：检测规格/计划目录模式

If specs/, rfcs/, adrs/, or similar directories exist:

List all subdirectories
Pick one representative and list its contents
Document the detected pattern (what files each entry contains)
List all entries with one-line descriptions
Identify active vs completed (check git history or task checkboxes)

If no formal spec system exists, note how the project tracks work (GitHub Issues, Jira, informal, etc.) if detectable.

如果存在 specs/、rfcs/、adrs/ 或类似目录：

列出所有子目录
选择一个代表性目录并列出其内容
记录检测到的模式（每个条目包含哪些文件）
列出所有条目并附上一行说明
确定活跃或已完成状态（检查 git 历史或任务复选框）

如果不存在正式的规格系统，则在可检测的情况下说明项目如何跟踪工作（GitHub Issues、Jira、非正式跟踪等）。

Step 5: Generate context files

第 5 步：生成上下文文件

Using the templates in

references/templates.md

, generate:

```
.ai/PROJECT.md
```
— from detected stack, architecture, and key documents
```
.ai/PATHS.md
```
— from discovered files and documentation
```
.ai/PLAN.md
```
— from active work (git branch, recent commits, spec status)
```
.ai/conversations/HANDOFF.md
```
— initial state with "system initialized" note
```
.ai/conversations/LOG.md
```
— header only

Use the real local system time for all dates. On Unix-like systems, get it with:

bash

date '+%Y-%m-%d %H:%M %Z'
date '+%Y-%m-%d/%H%M%S'

Never copy a date from old project docs, model memory, or previous handoff entries when creating new log/session records.

使用

references/templates.md

中的模板生成：

```
.ai/PROJECT.md
```
— 根据检测到的技术栈、架构和关键文档生成
```
.ai/PATHS.md
```
— 根据发现的文件和文档生成
```
.ai/PLAN.md
```
— 根据活跃工作生成（git 分支、近期 commit、规格状态）
```
.ai/conversations/HANDOFF.md
```
— 初始状态，并附“系统已初始化”说明
```
.ai/conversations/LOG.md
```
— 仅包含标题

所有日期均使用真实的本地系统时间。在类 Unix 系统上，可通过以下命令获取：

bash

date '+%Y-%m-%d %H:%M %Z'
date '+%Y-%m-%d/%H%M%S'

创建新的日志/session 记录时，绝不要从旧项目文档、模型记忆或之前的 handoff 条目中复制日期。

Step 6: Inject always-active snippet into agent config files

第 6 步：向 Agent 配置文件注入常驻代码片段

The

.ai/

files are useless unless agents actually read them. This step ensures every agent's config file contains the always-active snippet that drives the read-on-start / write-after-task behavior.

Read the snippet from

inject.md

(same directory as this SKILL.md file — check

.claude/skills/agent-handoff/inject.md

.agents/skills/agent-handoff/inject.md

For each agent config file below, check if it already contains the marker

## Agent Handoff (always active)

. If NOT present, append the full snippet. If already present, skip it.

Agent	Config file	When to inject
Claude Code	`CLAUDE.md`	Always — create the file if it doesn't exist
Codex (OpenAI)	`codex.md`	Always — create the file if it doesn't exist
Multi-agent / Antigravity	`AGENTS.md`	Always — create the file if it doesn't exist
Cursor	`.cursorrules`	Only if the file or `.cursor/` directory exists
Windsurf	`.windsurfrules`	Only if the file exists
Gemini CLI / older Antigravity	`GEMINI.md`	Only if the file exists or `.gemini/` exists
OpenCode	`.opencode/instructions.md`	Only if `.opencode/` directory exists
GitHub Copilot	`.github/copilot-instructions.md`	Only if `.github/` directory exists

If
inject.md
is not found, use this minimal fallback snippet instead:

markdown

undefined

只有在 Agent 实际读取

.ai/

文件时，这些文件才会发挥作用。此步骤确保每个 Agent 的配置文件都包含常驻代码片段，以驱动“会话开始时读取/任务完成后写入”的行为。

**读取代码片段：**从

inject.md

读取（与当前 SKILL.md 文件位于同一目录——检查

.claude/skills/agent-handoff/inject.md

或

.agents/skills/agent-handoff/inject.md

）。

**对于下方每个 Agent 配置文件，**检查其是否已包含标记

## Agent Handoff (always active)

。如果不存在，则追加完整片段；如果已存在，则跳过。

Agent	配置文件	注入时机
Claude Code	`CLAUDE.md`	始终——文件不存在则创建
Codex (OpenAI)	`codex.md`	始终——文件不存在则创建
Multi-agent / Antigravity	`AGENTS.md`	始终——文件不存在则创建
Cursor	`.cursorrules`	仅当该文件或 `.cursor/` 目录存在
Windsurf	`.windsurfrules`	仅当该文件存在
Gemini CLI / 旧版 Antigravity	`GEMINI.md`	仅当该文件存在或 `.gemini/` 存在
OpenCode	`.opencode/instructions.md`	仅当 `.opencode/` 目录存在
GitHub Copilot	`.github/copilot-instructions.md`	仅当 `.github/` 目录存在

**如果未找到

inject.md

，**则改用以下最小回退片段：

markdown

undefined

Agent Handoff (always active)

ON EVERY CONVERSATION START, read these files:

.ai/PROJECT.md
.ai/PATHS.md
.ai/PLAN.md
.ai/conversations/HANDOFF.md

If any are missing, empty, or placeholder-only, bootstrap/repair .ai/ before work. Use

date '+%Y-%m-%d %H:%M %Z'

for real local timestamps.

BEFORE YOU FINISH EVERY RESPONSE, complete the handoff write-back:

Append to .ai/conversations/LOG.md
Update .ai/conversations/HANDOFF.md if files changed or decisions made
Create a session file at .ai/conversations/sessions/YYYY-MM-DD/HHMMSS-agent-task-slug.md if files changed or decisions made
In your final response, mention that handoff was updated or explain why no handoff write was needed
Identify yourself by agent name in all writes

undefined

ON EVERY CONVERSATION START, read these files:

.ai/PROJECT.md
.ai/PATHS.md
.ai/PLAN.md
.ai/conversations/HANDOFF.md

If any are missing, empty, or placeholder-only, bootstrap/repair .ai/ before work. Use

date '+%Y-%m-%d %H:%M %Z'

for real local timestamps.

BEFORE YOU FINISH EVERY RESPONSE, complete the handoff write-back:

Append to .ai/conversations/LOG.md
Update .ai/conversations/HANDOFF.md if files changed or decisions made
Create a session file at .ai/conversations/sessions/YYYY-MM-DD/HHMMSS-agent-task-slug.md if files changed or decisions made
In your final response, mention that handoff was updated or explain why no handoff write was needed
Identify yourself by agent name in all writes

undefined

Step 7: Report to the user

第 7 步：向用户报告

Agent handoff system initialized.

Discovered: {N} reference documents, {N} feature specs, {N} archived docs.
Key documents: {list top 3}
Active work detected: {feature/branch or "none detected"}
Agent configs updated: {list of files where snippet was injected}
Gaps: {any missing elements like "no test directory found"}

Agent handoff system initialized.

Discovered: {N} reference documents, {N} feature specs, {N} archived docs.
Key documents: {list top 3}
Active work detected: {feature/branch or "none detected"}
Agent configs updated: {list of files where snippet was injected}
Gaps: {any missing elements like "no test directory found"}

Stale Detection

过期检测

HANDOFF.md stale (> 7 days since last update):

Do NOT blindly trust the handoff state
Run
```
git log --oneline --since="7 days ago"
```
to check what changed
Cross-reference git history with HANDOFF.md
Update HANDOFF.md with current state before proceeding

Add a note:

[stale] Handoff was {N} days old. Refreshed from git history.

PATHS.md references a file that no longer exists:

Remove the stale entry
Check if the file was renamed, moved, or superseded
Add the replacement if found
Log the cleanup in LOG.md

HANDOFF.md 已过期（距上次更新超过 7 天）：

不要盲目信任 handoff 状态
运行
```
git log --oneline --since="7 days ago"
```
检查发生的变化
将 git 历史与 HANDOFF.md 交叉核对
继续操作前，使用当前状态更新 HANDOFF.md

添加备注：

[stale] Handoff was {N} days old. Refreshed from git history.

PATHS.md 引用了已不存在的文件：

删除过期条目
检查文件是否已被重命名、移动或替代
如果找到替代文件，则添加该文件
在 LOG.md 中记录此次清理

Size Limits

大小限制

File	Max Lines	Enforcement
PROJECT.md	~80	Stable — only update when stack or architecture changes
PATHS.md	~150	Collapse less-important entries into directory summaries
PLAN.md	~60	Track active feature only. Completed → one-liner
HANDOFF.md	~100	Rolling window: max 15-20 Recent Completions. Oldest → LOG.md
LOG.md	~500	Archive entries older than 90 days to `LOG-archive-YYYY.md`
Session files	~80 each	Reference commit hashes instead of repeating diffs

Startup read cost: ~800-1500 tokens for all 4 files combined. Per-task write cost: ~500-1200 tokens depending on complexity.

文件	最大行数	执行方式
PROJECT.md	~80	稳定——仅在技术栈或架构变化时更新
PATHS.md	~150	将不太重要的条目汇总为目录摘要
PLAN.md	~60	仅跟踪活跃功能。已完成 → 一行说明
HANDOFF.md	~100	滚动窗口：最多保留 15–20 条 Recent Completions。最旧的条目 → LOG.md
LOG.md	~500	将 90 天前的条目归档到 `LOG-archive-YYYY.md`
Session 文件	每个约 80	引用 commit hash，而不是重复 diff

**启动读取成本：**4 个文件合计约 800–1500 tokens。 **每项任务的写入成本：**根据复杂度约 500–1200 tokens。

Concurrent Agent Safety

并发 Agent 安全

When two agents work simultaneously, file conflicts can occur.

Prevention:

HANDOFF.md Active Work lists what each agent is working on. Before starting, check if another agent is currently active.
Session files never conflict — each agent writes its own timestamped file.
LOG.md is append-only — conflicts are simple to resolve (keep both entries).

If a merge conflict occurs in HANDOFF.md:

Keep both agents' Active Work entries
Merge Recent Completions chronologically
Union all Key Context entries

当两个 Agent 同时工作时，可能发生文件冲突。

预防措施：

HANDOFF.md 的 Active Work 列出每个 Agent 正在处理的工作。开始前，检查是否已有其他 Agent 正在工作。
Session 文件永不冲突——每个 Agent 都会写入自己带时间戳的文件。
LOG.md 仅追加——冲突易于解决（保留两条记录）。

如果 HANDOFF.md 发生合并冲突：

保留两个 Agent 的 Active Work 条目
按时间顺序合并 Recent Completions
合并所有 Key Context 条目

Session File Protocol

Session 文件协议

Agents must create a session file whenever they modify files, make a decision, run an investigation that future agents may need, or take over another agent's active work.

Read the four startup files.
Get real local time from the environment.

Create the date directory:

mkdir -p .ai/conversations/sessions/$(date +%F)

Use this filename:

.ai/conversations/sessions/YYYY-MM-DD/HHMMSS-agent-task-slug.md

Keep the file short and factual. Link to changed files, docs, commits, tests, and blockers rather than pasting large diffs.
Reference the session file from HANDOFF.md Active Work or Recent Completions.
Append a matching LOG.md entry.
In the final response to the user, say that handoff was updated. If no write was needed, say why.

If an agent writes LOG.md/HANDOFF.md but no session file for a file-changing task, the handoff is incomplete and the next agent should repair it by creating a catch-up session file from available evidence.

Agent 在修改文件、做出决策、执行未来 Agent 可能需要的调查，或接手另一个 Agent 的活跃工作时，必须创建 session 文件。

阅读四个启动文件。
从环境中获取真实本地时间。

创建日期目录：

mkdir -p .ai/conversations/sessions/$(date +%F)

。

使用以下文件名：

.ai/conversations/sessions/YYYY-MM-DD/HHMMSS-agent-task-slug.md

。

保持文件简短且基于事实。引用已更改的文件、文档、commit、测试和阻塞项，而不是粘贴大型 diff。
在 HANDOFF.md 的 Active Work 或 Recent Completions 中引用 session 文件。
追加匹配的 LOG.md 条目。
在给用户的最终响应中说明 handoff 已更新。如果无需写入，说明原因。

如果 Agent 在涉及文件变更的任务中写入了 LOG.md/HANDOFF.md，却没有创建 session 文件，则 handoff 不完整，下一个 Agent 应根据现有证据创建补录 session 文件来修复。

Monorepo Projects

Monorepo 项目

Place
```
.ai/
```
at the repository root, not inside individual packages
PATHS.md should list all packages/services with their paths
PLAN.md can track work across packages — use package prefixes
Session files should note which package(s) were modified

将
```
.ai/
```
放在仓库根目录，而不是各个 package 内
PATHS.md 应列出所有 package/服务及其路径
PLAN.md 可以跨 package 跟踪工作——使用 package 前缀
Session 文件应注明修改了哪些 package

Rules

规则

Always read before work. The 4 context files at conversation start. No exceptions.
Always write after work. Even for Q&A — a question answered today is context tomorrow.
Be concise in LOG.md. 3-5 lines per entry. Full details in session files.
Respect size limits. Archive LOG.md when it exceeds ~500 lines.
Promote decisions. Architecture/design choices →
```
decisions/
```
directory.
Don't duplicate git history. Reference commit hashes, not diffs.
Use real timestamps. Never placeholders.
Tag every LOG.md entry. Tags enable scanning.
Keep PATHS.md accurate. New file or doc → update PATHS.md.
Update PLAN.md on progress. Mark tasks done, add blockers, note the agent.
Progressive disclosure. HANDOFF.md → session file → source files.
Identify yourself. Include agent name in all writes.
LOG.md is append-only. Never delete entries.
Verify on resume. Check files exist before continuing another agent's work.
Read docs before implementation. Check PATHS.md for relevant specs/plans.
Index new documents immediately. Don't leave them for the next agent.
Current over archived. Never reference an archived doc as authoritative.
Record your sources. List consulted docs in session file References section.

工作前始终读取。 会话开始时读取 4 个上下文文件。毫无例外。
工作后始终写入。 即使只是问答——今天回答的问题就是明天的上下文。
在 LOG.md 中保持简洁。 每条记录 3–5 行。完整详情写入 session 文件。
遵守大小限制。 LOG.md 超过约 500 行时进行归档。
提升决策。 架构/设计选择 →
```
decisions/
```
目录。
不要重复 git 历史。 引用 commit hash，而不是 diff。
使用真实时间戳。 绝不使用占位符。
为每条 LOG.md 记录添加标签。 标签便于扫描。
保持 PATHS.md 准确。 新文件或文档 → 更新 PATHS.md。
在进展更新时更新 PLAN.md。 标记任务完成，添加阻塞项，注明 Agent。
渐进式披露。 HANDOFF.md → session 文件 → 源文件。
标识自己。 所有写入中都包含 Agent 名称。
LOG.md 仅追加。 绝不删除条目。
恢复时进行验证。 继续另一个 Agent 的工作前，检查文件是否存在。
实现前阅读文档。 查看 PATHS.md 以找到相关规格/计划。
立即索引新文档。 不要留给下一个 Agent 处理。
当前版本优先于归档版本。 绝不将归档文档作为权威依据。
记录来源。 在 session 文件的 References 部分列出查阅过的文档。