Communitygithub.com

handoff(工作交接)

打印当前会话的快照(SHA、树状态、已合并PR、主要发现、下一步计划),仅对下一周期的工作创建真实议题,并将因决策延期的事项记录在决策所在处。用于“收尾”或“交接”场景。

handoff(工作交接) 是什么?

该技能专为AI代理(如Claude Code、Codex等)设计,在会话结束时生成结构化的交接快照。它记录树状态(SHA、工作树、开放PR)、自上一版本标签或会话开始以来已合并的PR,以及一个关键发现。其核心机制是将下一步行动转化为GitHub议题——每个具体项在创建前会先匹配已有的开放议题,避免重复。对于因有意识决策而延期的事项,不会创建普通议题,而是在决策本来的位置(如CHANGELOG、决策记录、代码注释)记录理由,只有在没有任何现有位置时才创建立即关闭的议题作为占位。该技能故意不复制门控判定或计数表的结果,因为接收者应基于记录的SHA重新运行来获得可信数据。交接快照始终以过时声明开头,强调信息是快照态,仓库可能已经变化。它支持GitHub CLI不可用或未认证时的降级模式,并在对应的GitHub Actions工作流(如apply-triage.yml)中触发,确保只在明确请求时执行,避免自动操作影响议题状态。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dubbl-a/house-rules/tree/HEAD/plugins/house/skills/handoff

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

交接(Handoff)

交接打印一个快照:下一个会话首先读取的固定格式摘要。它不会为快照本身归档任何内容,因为快照可以从默认分支、已合并PR和发布说明中重新推导得出,并且一个只会反复陈述相同内容的常驻议题是无用噪音。它只为将要有人执行的工作创建议题:每个下一周期的项都会变成一个议题,但首先会与现有的开放议题进行匹配。因决策而延期的事项,会在决策原本所在的位置记录其理由,因为该理由是下一个会话无法自行重构的唯一信息。

工具链已支持使用 --continue 或 --resume 恢复会话完整历史,并保留机器本地的自动记忆,因此快照仅携带这些无法承载的信息:下一步行动和另一个机器或人员需要在仓库或议题中找到的决策。门控判定和计数表故意不包含在快照中:两者都可以在几秒钟内根据记录的SHA重新运行,而且重新运行的结果无法像复制的内容那样被捏造。

此技能可以创建和关闭议题,因此绝不会自动触发。仅在明确要求时运行,并且仅在会话实际结束的时间点运行。

默认流程

  1. 收集树状态:SHA、工作区是否干净、工作树个数、开放PR。
  2. 列出自上一个发布标签以来(如果没有标签,则从会话开始以来)已合并的PR。
  3. 陈述一个主要发现,并附上证据。
  4. 编写下一周期工作列表:有序、具体,每个项都带有理由。
  5. 对每个下一周期项,检查开放议题中是否已有涵盖它的议题;仅在没有找到时才创建新议题,并记录其编号。
  6. 对于因决策延期的事项,在决策原本所在的位置(CHANGELOG、决策记录、相关代码注释)记录理由;仅当没有这样的位置时,才创建一个标记为“非计划”并关闭的议题。不要对仅仅未完成的事情做此操作;那要么仍然是下一周期项,要么静默丢弃。
  7. 遗留清理:如果存在标题为“Session carryover”的开放议题,则关闭它,并附上一条评论指向其内容被拆分后的议题。
  8. 在回复中打印快照:过时声明、树状态、已合并PR、主要发现、带议题编号的下一周期列表、以及记录了延期决策的位置。

收集树状态

针对仓库的默认分支(而非会话当前所在的分支)运行以下命令:

git rev-parse HEAD
git status --short
git worktree list
gh pr list --state open

记录确切的SHA、工作树是否干净、工作树数量、以及开放PR的数量。模糊的“一切进展良好”不是树状态;SHA是让下一个会话确认其下没有变化的事实,并且它是每个门控和计数重新运行的依据,这就是为什么这些结果不会被归档到任何地方。

列出已合并内容

从上一个发布标签(如果没有,则从会话开始)到当前HEAD,列出每个已合并的PR,每行一个:编号及其作用。如果没有合并任何内容,则在此标题下写入“无”。不要因为列表为空就省略标题;缺少一段内容会被解读为“没人检查过”,而不是“没有东西合并”。

陈述主要发现

一个发现,以带有证据的决策形式陈述,而不是所有发生事情的摘要。如果本次会话没有达到这个标准的发现,则写入“本次会话无主要发现”,而不是为了填充而夸大一个次要观察。

编写下一周期列表,并将每个项转为议题

一个有序的具体下一步行动列表,每个项都带有促使其产生的单行理由。“从这里开始”意味着第一个项确实是下一个会话应开始的地方,而不是第一个想到的事情。

对于每个项,先搜索开放议题再创建新议题:

gh issue list --search "<项摘要>" --state open

如果已有开放议题涵盖它,则使用该议题的编号。否则创建一个:

gh issue create --title "<项>" --body "<单行理由>"

议题存在的意义是供人执行工作;一个从未变成议题的下一周期项,只是一个需要下一个会话信任的散文列表,而不是一个可以基于其行动的可追踪项。

在决策所在位置记录延期决策

本次会话选择刻意不做某件事,与仅仅没有轮到本次会话做的事情是不同的。只有前一种情况需要记录理由,记录在决策已经存在的位置:相关发布的CHANGELOG条目、决策记录、或相关地点的代码注释。在快照中指向该位置。仅在没有这样的位置时,才将其归档为已关闭的议题:

gh issue create --title "<项>" --body "因决策延期:<理由>"
gh issue close <N> --reason "未计划"

理由是下一个会话无法自行重构的唯一一行信息;一件仅仅未完成的事情无需记录,因为它要么仍然是下一周期项,要么从未是承诺。

遗留:关闭一个开放的遗留议题

如果在此做法变更之前,仍有一个标题为“Session carryover”的议题是开放的,则关闭它,而不是让其永远开放:

gh issue list --search "Session carryover" --state open
gh issue close <N> --comment "已退役:拆分为 <来自本次交接的议题编号>。"

一旦没有这样的议题残留,跳过此步骤。

打印快照

以过时声明开始,精神上逐字对应:“在使用前验证任何内容,这是一个快照,仓库会发生变化。”然后按顺序:树状态、已合并PR、主要发现、每个项带有议题编号的下一周期列表、以及记录了延期决策的位置。在回复中打印这些内容;它不会被归档。

应急出口

  • 没有 gh CLI,或未认证。 仍然打印快照以及下一周期和延期决策项,说明无法创建议题,让人员手动提交。
  • 没有东西合并、没有主要发现、没有下一周期项、或没有延期决策。 在该部分中明确说明,而不是省略或填充。

禁止事项

  • 不要自动运行此技能。它可以创建和关闭议题,并且仅在请求时触发。
  • 不要复制门控判定或计数表到快照中;它们可以从记录的SHA重新运行,读者信任的是重新运行的结果,而不是副本。
  • 不要在不检查是否有已有议题涵盖的情况下为下一周期项创建议题。
  • 不要为仅仅未完成的事情创建议题;这与因决策延期不同。
  • 不要因为感觉会话是当前的而跳过过时声明;下一个读者无法不通过声明而知道这一点。
  • 不要为了看起来内容丰富而填充缺失的主要发现或空白的已合并列表。
  • 一旦本次交接运行完毕,不要保持“Session carryover”议题开放。

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

相关技能