Skill 工具嵌入指南
概述
本 Skill 沉淀了在将 TodoWrite 和 AskUserQuestion 工具嵌入已有 Skill 文件的经验和最佳实践。
适用场景
- 为一个多阶段的 Skill 增加进度追踪（TodoWrite）
- 在 Skill 的确认点/决策点增加结构化用户提问（AskUserQuestion）
- 统一多个 Skill 的工具调用风格
> 适用说明： 本 Skill 专为 Trae IDE 的 Skill 开发流程设计，其中的工具调用方式和文件结构约定均基于 Trae IDE 的 Agent 交互规范。在其他 IDE 或平台中使用时可能需要进行适配调整。
一、TodoWrite 嵌入模式
1.1 核心原则
| 原则 | 说明 |
|---|---|
| 粗粒度 | 每个阶段/步骤一条，不细化到子步骤 |
| 入口创建 | 在 SKILL.md 的「工作流程」之后创建全局列表 |
| 阶段过渡更新 | 每个阶段文件末尾更新一次 |
| 确认点独立条目 | 确认点单独占一条，与阶段并列 |
1.2 嵌入位置
位置 A — SKILL.md（入口处）
在「工作流程」表或流程图之后，--- 分隔线之前，新增「进度追踪」小节：
### 进度追踪
进入阶段一之前，**立即使用 TodoWrite 工具创建以下全局进度追踪列表**（`merge=false`，N项全部创建）：
| # | 内容 | 初始状态 |
|---|------|---------|
| 1 | 第一阶段名称 | `in_progress` |
| 2 | ✋ 确认点名称 | `pending` |
| 3 | 第二阶段名称 | `pending` |
| ... | ... | `pending` |
每完成一个阶段/确认点，使用 `TodoWrite(merge=true)` 将对应项标记为 `completed`，下一项标记为 `in_progress`。
位置 B — 每个阶段文件末尾
在 --- 分隔线之前、→ 进入下一步 之前插入：
**→ 进度更新：** 使用 `TodoWrite(merge=true)` 将「当前阶段名称」标记为 `completed`，将「下一阶段名称」标记为 `in_progress`。
1.3 粒度标准
✅ 正确（粗粒度）：
阶段一：对齐讨论
✋ 确认点 A
阶段二：生成规划文档
❌ 错误（过细）：
阶段一：阅读文件
阶段一：整理要点
阶段一：向用户展示
✋ 确认点 A
1.4 过渡写法模板
| 场景 | 写法 |
|---|---|
| 阶段 → 下一阶段 | 将「阶段X：名称」标记为 completed，将「阶段Y：名称」标记为 in_progress |
| 阶段 → 确认点 | 将「阶段X：名称」标记为 completed，将「确认点 X」标记为 in_progress |
| 确认点 → 阶段 | 将「确认点 X」标记为 completed，将「阶段Y：名称」标记为 in_progress |
| 最后阶段完成 | 将「最后阶段：名称」标记为 completed |
二、AskUserQuestion 嵌入模式
2.1 核心原则
| 原则 | 说明 |
|---|---|
| 在确认点使用 | 只用在需要用户决策的地方，不用在信息展示处 |
| 一次性展示全部 | 不要逐个问题问，一次汇总所有选项 |
| 选项 ≠ 后续步骤 | 选项是用户的选择，后续操作是 AI 的反应 |
| 标准化参数 | 统一使用 question + header + options 格式 |
2.2 标准化格式
使用 `AskUserQuestion` 工具：
- **question**：「询问用户的问题？」
- **header**：「简短标签（≤12字）」
- **options**：
1. 「选项一标签」 — 选项一描述
2. 「选项二标签」 — 选项二描述
3. 「选项三标签」 — 选项三描述
根据用户的选择执行对应操作：
| 用户选择 | 后续操作 |
|---------|---------|
| 选项一标签 | 操作 A |
| 选项二标签 | 操作 B |
| 选项三标签 | 操作 C |
2.3 选项设计要点
- 选项数量：2-4 个（太少像二选一，太多显得散）
- 标签 vs 描述：标签简短（≤8字），描述说明后果（10-20字）
- 选项互斥：彼此不重叠，覆盖所有合理路径
- 明确的后续动作：每个选项对应一个具体的后续操作
- 包容"调整"路径：至少有一个选项允许用户说「需要修改」
2.4 典型确认点模板
确认点 A（理解对齐）：
- **question**：「以上对本章的理解是否正确？」
- **header**：「确认点 A」
- **options**：
1. 「完全符合预期」 — 进入下一阶段
2. 「局部需要调整」 — 根据反馈修改后再次展示
3. 「理解有偏差」 — 重新阅读文件后再次展示
确认点 B（规划确认）：
- **question**：「规划是否符合预期？」
- **header**：「确认点 B」
- **options**：
1. 「符合预期，继续」 — 进入下一阶段
2. 「需要调整」 — 根据反馈修改后再次确认
3. 「重新规划」 — 回到上一阶段
确认点 C（记忆更新确认）：
- **question**：「是否执行以上更新？」
- **header**：「记忆更新确认」
- **options**：
1. 「全部更新」 — 执行所有维度的变更
2. 「只更新 XX 和 YY」 — 只执行指定的维度
3. 「只看不更，我自己判断」 — 不写入，仅展示报告
4. 「重新评估」 — 回到步骤二重新评估
三、TodoWrite + AskUserQuestion 组合模式
两个工具职责分明，在同一流程中配合使用：
| 工具 | 职责 | 调用时机 |
|---|---|---|
| TodoWrite | 记录"做到哪一步了" | 入口创建 + 每个阶段/确认点过渡时 |
| AskUserQuestion | 让用户做决策 | 每个确认点（用户选择后 TodoWrite 再更新） |
典型流程时序
① 进入阶段一 → 创建全局 TodoWrite 列表（阶段一 in_progress）
② 完成阶段一工作 → TodoWrite（阶段一 ✅ → 确认点 A ▶️）
③ 到达确认点 A → AskUserQuestion（向用户提问）
④ 用户选择「符合预期」→ TodoWrite（确认点 A ✅ → 阶段二 ▶️）
⑤ 完成阶段二工作 → TodoWrite（阶段二 ✅ → 阶段三 ▶️）
⑥ ...以此类推
⑦ 所有阶段完成 → TodoWrite（最后阶段 ✅）
一个文件内的完整示例（阶段文件末尾）
**→ 进度更新：** 使用 `TodoWrite(merge=true)` 将「阶段一：对齐讨论」标记为 `completed`，将「确认点 A」标记为 `in_progress`。
---
**→ 进入确认点 A：使用 AskUserQuestion 向用户确认。**
向用户展示整理结果后，使用 `AskUserQuestion` 工具：
- **question**：「以上对本章的理解是否正确？」
- **header**：「确认点 A」
- **options**：
1. 「完全符合预期」 — 进入阶段二
2. 「局部需要调整」 — 根据反馈修改后再次展示
3. 「理解有偏差」 — 重新阅读文件后再次展示
根据用户的选择执行对应操作：
| 用户选择 | 后续操作 |
|---------|---------|
| 完全符合预期 | 使用 TodoWrite 更新进度，进入阶段二 |
| 局部需要调整 | 根据反馈修正展示内容，再次请用户确认 |
| 理解有偏差 | 重新阅读必读文件，整理后再次展示 |
用户选择「完全符合预期」后，使用 `TodoWrite(merge=true)` 将「确认点 A」标记为 `completed`，将「阶段二：生成章节设计文档」标记为 `in_progress`，然后进入阶段二。
四、嵌入后自检清单
操作前后对照表
在嵌入工具前后，对比以下关键差异，确保嵌入正确：
| 检查项 | 嵌入前（错误状态） | 嵌入后（正确状态） |
|---|---|---|
| 进度展示 | 纯文字描述"进入阶段 X" | TodoWrite 列表 + 状态标记 |
| 用户确认 | 模糊的「等待用户确认」 | 标准 AskUserQuestion（question + header + options） |
| 阶段过渡 | 无明确进度更新提示 | 每个阶段末尾有 TodoWrite transition |
| 创建 vs 更新 | 未区分 merge 模式 | 创建用 merge=false，更新用 merge=true |
TodoWrite 检查
- [ ] SKILL.md 中是否在入口处创建了全局追踪列表？
- [ ] 列表项是否是粗粒度（每阶段/确认点一条）？
- [ ] 第一项初始状态是否为
in_progress？ - [ ] 每个阶段文件末尾是否有 TodoWrite 更新？
- [ ] 确认点过渡处是否有 TodoWrite 更新？
- [ ] 最后阶段完成后是否有 TodoWrite 标记 completed？
- [ ] 创建时用
merge=false，更新时用merge=true？ - [ ] 对照上表确认操作前后状态已正确转换？
AskUserQuestion 检查
- [ ] 确认点处是否替换了模糊的「等待用户确认」？
- [ ] 是否标准化为 question + header + options 格式？
- [ ] 选项数量是否在 2-4 个之间？
- [ ] 每个选项是否有明确的后续操作映射？
- [ ] 是否至少有一个选项允许用户提出调整/修改？
- [ ] 选项标签是否简短（≤8字）且彼此互斥？
- [ ] 对照上表确认嵌入前的问题已全部替换？
五、常见错误与恢复
5.1 TodoWrite 常见错误
| 错误 | 现象 | 恢复方法 |
|---|---|---|
| merge 模式用错 | 进度列表被整表替换而非更新 | 重新创建列表（merge=false）后，再逐条更新（merge=true） |
| 粒度太细 | 列表有 10+ 条，显得冗余 | 合并为粗粒度条目（每阶段 1 条 + 确认点 1 条） |
| 入口未创建 | 阶段文件中直接引用了未创建的条目 | 回到 SKILL.md 入口处创建全局列表 |
| 状态跳跃 | 跳过 in_progress 直接标 completed |
按序恢复：将当前项改回 in_progress，前一项改回 completed |
| 列表项名称不一致 | TodoWrite 引用的名称与创建时不同 | 统一名称后再更新，避免 orphan 条目 |
5.2 AskUserQuestion 常见错误
| 错误 | 现象 | 恢复方法 |
|---|---|---|
| 缺少「调整」选项 | 用户只能接受或拒绝，没有中间路径 | 补充一个调整选项，例如「局部需要调整」 |
| 选项不互斥 | 用户难以选择 | 重新设计选项，确保彼此边界清晰 |
| options 格式不规范 | 工具调用失败或解析错误 | 检查 question/header/options 字段是否齐全 |
| 确认点位置不当 | 不该确认的地方弹出了提问 | 将 AskUserQuestion 移到真正需要决策的节点 |
5.3 通用恢复流程
如果嵌入过程中出现问题，按以下步骤恢复：
- 立即停止：暂停当前修改，不要继续操作
- 检查自检清单：逐项核对，找出不一致的地方
- 修正 TodoWrite：确保列表项名称、顺序、merge 模式正确
- 修正 AskUserQuestion：确保格式标准、选项完整
- 重新验证：再次过一遍自检清单确认修复完成
六、FAQ
Q1：TodoWrite 和 AskUserQuestion 必须成对使用吗？
不必。两者是独立的工具，可以根据 Skill 的实际需求单独使用。短流程（2-3 步）只需 TodoWrite 即可；需要用户决策的节点才加入 AskUserQuestion。
Q2：一个 Skill 中最多可以用几个确认点？
建议不超过 3 个。过多的确认点会打断用户体验。如果确实需要更多，考虑合并逻辑相关的确认点。
Q3：合并确认点和阶段过渡的 TodoWrite 调用？
先调用 AskUserQuestion 让用户做决策，根据用户选择更新 TodoWrite，再进入下一步。具体时序参考第三章的组合模式示例。
Q4：子 Tick 文件也需要嵌入 TodoWrite 吗？
不需要。TodoWrite 只在主 SKILL.md 的入口创建一次，子阶段文件中只需在末尾写过渡更新指令即可。
Q5：如果用户在选择 AskUserQuestion 后反悔了怎么办？
在「用户选择 → 后续操作」映射表中，始终保留一个「重新评估」或「回到上一步」的选项路径，让用户可以回溯。
Q6：嵌入后需要测试什么？
主要验证两点：① 所有 TodoWrite 引用的条目名称与创建时一致；② 所有 AskUserQuestion 的选项都有对应的后续操作映射。对照自检清单过一遍即可。
