用途:把一个延续任务转成一份自包含的交接文件,交给全新的智能体会话执行。它只写交接文件,不实现、不修改跟踪文件、不提交或推送、不启动 Codex、不改忽略配置。简单任务一份文件即可直接执行;复杂任务需解析 ~/.agents/skills/orchestration 的绝对目录,要求 SKILL.md 可读,并把该绝对路径写入交接文件,指示接收会话在 Plan 模式加载它作为任务规格。
选择工作:可用 $ARGUMENTS;否则从最近回复与记录推断下一步。写作前先解析可发现事实,区分已完成、部分完成与剩余工作;任务已完成则报告证据、不创建文件。仅当未决选择实质影响范围、安全、执行方式、验证、仓库归属或放置位置时才提问。
分类:从用户期望结果、证据与授权动作判定,恰选一个小写类别:implementation、investigation、research、audit、operations。执行方式分 simple 或 complex;仅当委派能实质改善延迟、正确性或验证时才标 complex,文件与仓库数量本身不是复杂度信号。
放置:单仓库放在 <REPOSITORY>/.ai/task-handoffs/<HANDOFF_NAME.md>;跨仓库仅当跨越至少两个仓库时放在 ~/Desktop/.ai/task-handoffs/<HANDOFF_NAME.md>。文件名需匹配 ^[A-Z][A-Z0-9](_[A-Z0-9]+)[.]md$。
创建:草稿写在涉及仓库之外的临时目录,非空、以一个 H1 开头、无 YAML frontmatter,不写 ## Handoff category、## Execution status、## Handoff cleanup。正文需决策完整,含目标、成功标准、明确排除项、已验证现状与部分改动、按稳定路径或符号或命令标注的改动、任务专属证据与边缘情况、验证与发布要求、精确写入范围,以及 ai-coord draft 或 bundle draft 命令与 promote 命令。
发布:草稿完整后单次调用 ai-handoff create,可用 --check 先做校验。CLI 校验草稿并追加 YAML frontmatter 及固定契约,原子发布且不覆盖,复制生成的 Codex 命令。错误写入 stderr,用法错误退出 2,运行错误退出 1。接收代理完成交接后运行 ai-handoff archive 归档。非交互 discovery triage 可用 --no-clipboard 模式。
限制:技能自身不授予审批或覆盖接收端限制;不确定仓库集合或操作顺序时在写入前停止;复杂任务若无法解析已安装技能也需停止。具体命令与选项细节以原技能文本为准。