Agent Skills 工程化实践 12：handoff、teach、writing-for-agents 与 wizard 的共同边界
逐一解释 handoff、teach、writing-for-agents 与 wizard：如何跨 session 交接、建立长期学习、编写可预测的 Agent 文档，并把人工步骤变成安全向导。
这四个 Skills 都在设计“谁接着做”
它们看起来分散：一个写交接，一个教人，一个写 Agent 文档，一个生成 bash wizard。共同点是把 context 交给另一个执行者：fresh agent、学习者、未来的 model run，或拥有权限的人。
高质量交付不只要求当前 Agent 得出正确结果，还要让接收者知道从哪里继续、如何验证、哪些事情必须由自己决定。
handoff：只在 context 需要搬家时使用
触发方式：User-invoked。 可带上下一 session 的目的：
/handoff 下一次 session 将在 prototype 目录里验证状态机它把当前 conversation 压缩成临时目录中的 handoff document，并建议下一位 Agent 使用哪些 Skills。它引用现有 specs、ADRs、issues、commits 与 diffs，不复制这些 artifact 的正文；同时 redacts secrets 与个人敏感信息。
handoff 不是所有长 session 的默认结束方式。下一 phase 仍需要当前 context 时应 continue；历史已无用时 /clear；同一环境只是 context 太长时通常 /compact；只有需要换 harness、目录、同事或 side task 时，portability 才值得 handoff 成本。
上游 Skill：handoff
teach：把一次回答变成长期学习系统
触发方式：User-invoked。 它面向“我要学会”，不是“告诉我答案”：
/teach 我想学会设计可靠的 event-driven workflowsSkill 把当前目录当作 stateful teaching workspace，维护 MISSION.md、RESOURCES.md、learning-records/*.md、reference/*.html 与 lessons/*.html。每节 lesson 围绕 mission 中的真实动机，只教一个紧密主题，并根据 learning records 估计下一步 zone of proximal development。
它适合跨多个 session 的学习目标，不适合一次性解释 API。成功不是生成很多漂亮 HTML，而是学习记录能说明用户已经掌握什么、仍有哪些 misconception、下一课为什么处于“够难但可达”的位置。
上游 Skill：teach
writing-for-agents：提高过程稳定性，不追求固定答案
触发方式：Model-invoked。 创建或修改 Skill、AGENTS.md、CLAUDE.md，以及 Agent 通过 pointer 才会读取的文档时触发：
请用 writing-for-agents 重写 AGENTS.md，让 testing 规则只在改动 TypeScript package 时触发。核心概念是 context pointer：常驻 context 中的一小段话，说明某份材料是什么，以及哪些 branch 应该触发读取。pointer wording 决定 Agent 会不会到达目标；把重要规则藏在模糊链接后面，是 variance bug。
写作目标是让不同 runs 采取同一 process，而不是强迫它们输出同一句话。规则要 front-load trigger、每个 branch 只写一次、把 hard dependency 放在正确位置，并用 completion criteria 定义什么时候可以停止。Skill frontmatter、invocation choice 与 router 机制还需要配套阅读 SKILL-MECHANICS.md。
上游 Skill：writing-for-agents
wizard：让人完成 Agent 没有权限完成的步骤
触发方式：Model-invoked。 适合 provisioning、credentials、CI secrets、陌生 dashboard、one-off migration 或 cutover：
请用 wizard 生成 Cloudflare Pages 自定义域名切换向导；需要人登录和确认的步骤交给我，能自动验证的步骤由脚本执行。它生成 interactive bash script，复用固定 template 提供阶段进度、confirmation gates、跨平台打开 URL、隐藏 secret 输入、幂等 .env 更新以及 gh secret/gh variable 写入。Agent 的工作是确定 manual procedure 与 stages，不是重写 template library。
Wizard 默认 ephemeral：一次执行后可以删除；只有团队需要可重复 setup path 时才提交到 repo。它也不应包裹 Agent 自己能完成的命令——能自动完成就直接完成，把人留给权限、不可逆选择与外部 dashboard。
上游 Skill：wizard
25 个 promoted Skills 的完整覆盖
到这里，系列后半部分已经逐一覆盖 upstream README 当前列出的 25 个 promoted Skills：
- 07：
setup-matt-pocock-skills、ask-matt、wait-what； - 08：
grill-me、grilling、grill-with-docs、domain-modeling、to-questionnaire； - 09：
triage、to-spec、to-tickets、wayfinder； - 10：
implement、tdd、diagnosing-bugs、prototype、research； - 11：
codebase-design、improve-codebase-architecture、code-review、resolving-merge-conflicts； - 12：
handoff、teach、writing-for-agents、wizard。
skills/in-progress/ 与 skills/misc/ 中的 10 项内容会在下一篇单独说明：前者明确尚在试验，后者是特定工具与迁移任务。真正采用时应先从 promoted set 中建立团队自己的 trigger vocabulary，再按重复出现的实际问题引入其他 Skills。
最后一个判断：不要追求“全自动”
这些 Skills 最成熟的地方不是覆盖面，而是反复留下 ownership boundary：Agent 查事实，人做决定；Agent 生成脚本，人持有权限；Agent 压缩 context，接收者决定是否继续；Agent 写规则，团队审阅这些规则是否真的代表自己的工程方式。
当自动化保留了这些接管点，速度才不会以可理解性和责任边界为代价。
来源与版本
- 25 个 promoted Skills 清单：README Reference
- Latest Release：
v1.2.3 - 参考分支：
main· 核验 commit：8b78b53· 核验日期：2026-08-14