向导

它的作用¶

wizard 会生成一个交互式 bash 脚本，逐步引导人工完成手动流程：配置第三方服务、运行一次性迁移、将项目从状态 A 移动到状态 B。它会打开每个 URL，说明要点击和复制什么，捕获返回的内容，并将其写入 .env 文件和 GitHub Actions 机密。

智能体 编写脚本；它从不运行脚本。由你在自己的机器上运行。向导是一个程序，而不是一份说明列表。脚本按顺序执行每个步骤，并保留你输入的值。你只需要点击、粘贴并按 Enter。

何时使用¶

你可以输入 /wizard，智能体也可以自行使用它。当它遇到必须由你执行的步骤（例如它无法生成的密钥、它无法点击的仪表盘）时，它会为你构建一个向导，而不是把说明写进聊天中，让它们被滚动掉。

当阻塞你的下一步是穿过一个仪表盘时，请使用它：

不要用它来决定要构建什么；对于这一点，grill-with-docs 和 to-spec 才是合适的工具。

前置条件¶

生成它不需要任何前置条件。它编写的向导运行在 bash 上，并在某个阶段设置 GitHub 机密或变量时使用 gh。如果缺少 gh 或未认证，运行不会失败。该阶段会显示警告，结尾摘要会告诉你需要手动设置什么。

阶段¶

一个阶段是一个屏幕上的一个专注任务。脚本在阶段之间清除终端，因此超出屏幕的阶段会丢失被滚动掉的部分。你按依赖顺序编写阶段，并设置 TOTAL_STAGES，它驱动进度显示。

技能 在编写任何脚本之前都会界定流程范围。它读取仓库，而不是凭空询问：.env*、docker-compose*、框架配置，以及 .github/workflows/ 中每个 secrets.* / vars.* 引用。这些引用中的每一个都是向导必须生成的值。然后它会向你展示有序阶段列表以确认。只有在你确认后，它才会将每个阶段映射到人工遵循的精确路径（"仪表盘 → 开发者 → API 密钥 → 显示测试密钥 → 复制"）。对于它不知道当前 UI 的地方，它会询问你或查看文档，而不是凭空编造点击。

对于每个捕获的值，范围界定决定它去哪里：

模板已经解决了用户体验¶

模板 提供了完整体验：带剩余时间的进度、确认门、跨平台 URL 打开（包括 WSL）、机密隐藏输入、幂等的 .env 插入或更新、gh secret / gh variable 写入，以及一个结尾摘要，列出它必须跳过的所有内容。STAGES 标记上方的所有内容都是固定库，在每个向导中都相同，并且从不手动编辑。由于库从不改变，每个向导的行为都相同。每个向导唯一的工作是界定流程并编写其阶段。

编写向导的智能体从不端到端运行它，因为脚本会打开浏览器并等待人工输入。智能体改为进行静态检查：bash -n、可用时的 shellcheck，以及追踪每个值都落在范围界定所说的位置，并且每个 set_secret 名称都匹配 CI 中真实的 secrets.* 引用。因此第一次运行由你完成，而那次运行就是测试。

默认是临时的¶

常见问题¶

我的 API 密钥会进入模型上下文吗？

不会。智能体编写脚本；它不运行脚本。你自己运行脚本，脚本通过隐藏的终端输入捕获密钥，并直接写入 .env 或 gh secret。向导是一个 CLI，模型没有连接到它。这只适用于向导在运行时捕获的值。如果你在界定流程时将密钥粘贴到聊天中，它会像任何其他粘贴文本一样进入上下文。

我能返回并修正我打错的值吗？

运行中不能。没有返回按钮。阶段向前执行，第 3 阶段回答错误意味着 Ctrl-C 并重新运行。重新运行成本很低，因为任何已写入 .env 的值都会作为默认值再次提供，因此你可以按 Enter 通过你做对的阶段，只重新输入错误的那个。用户在发布周要求了这个功能，该请求仍然开放：“太喜欢了！不过有一点，有没有办法返回并更正你输入的内容？”

它知道我已完成哪些设置吗？

部分知道，而且比发布时的反响所假设的要少。它在询问之前会读取仓库（你的 .env 文件、docker-compose、框架配置、CI 中的 secrets.* 引用），因此它会针对缺失的值进行范围界定，而不是像 README 那样从零开始。它不会检查第三方服务。如果某个密钥已存在于你的 .env 中，向导会将其作为默认值提供，按 Enter 即可保留；如果你已经创建了 Stripe 账户但从未保存密钥，向导仍会把你带到它的仪表盘。

它在工作流中的位置在哪里，是在 grilling 和 spec 之后吗？

没有特定位置。它是独立步骤，不是链式步骤。常见猜测是 /grill-with-docs → /to-spec → /wizard，这个顺序没问题，但触发条件是出现一个手动流程，这可能发生在任何时间点：开始之前、构建中途，或发布很久之后。它也可以作为发现工具使用。范围界定会在你投入工作之前，发现任务的隐藏前置条件，比如你没想到过的三个 API 密钥。

它在 Claude Code 之外能用吗？

脚本可以。它是纯 bash，无论由哪个 harness 生成，运行方式都一样。技能本身是模型调用的，因此它会在所有地方列出：在 Claude Code 中输入 /wizard，在 Codex 中输入 $wizard，或者直接描述你卡住的设置。作为模型调用技能，它也避开了 #693，在该问题中，Claude 的桌面和 Web 应用会从 model 的列表中移除 用户调用 技能，并报告它们未安装。

它以前不是用户调用的吗？

是的。它现在是模型调用的，因此当 agent 遇到必须由你执行的步骤时，会主动使用它。你之前能做的所有事情仍然有效。模型调用让 agent 也能像你一样调用该技能，因此 /wizard 的行为和以前一样。这一更改修复了一个故障。以前，agent 在构建中途遇到凭据墙时，会把六个编号步骤倾倒到聊天中，让你手动执行。现在它会生成一个 wizard。

它以前在 in-progress/ 中。现在在哪里？

engineering/，从 v1.2 开始。它从 beta 桶毕业，现在随插件发布，因此它会随其他已提升的集合一起提供，而不需要单独安装。毕业时其行为没有变化。

如果它正常工作¶

• 在任何脚本存在之前，你会看到一个有序的阶段列表，以及每个阶段产生的值，并被要求确认。
• 在要求输入来自该页面的值之前，每个 URL 都会先打开。你永远不会被要求粘贴你尚未被引导去获取的内容。
• 密钥以盲输方式输入。没有任何敏感内容回显到你的滚动缓冲区。
• 每个阶段占一屏。你仍然需要的内容不会滚出屏幕。
• Ctrl-C 后重新运行会从你中断的地方继续，并将已保存的值作为默认值提供。
• 最终屏幕列出它写入的内容，并单独列出它无法完成、需要你手动完成的内容。

它的适用位置¶

wizard 是一个可随时取用的独立工具，位于自动化停止、需要人工点击的边界上。它最近的邻居是 setup-matt-pocock-skills，因为两者都旨在让仓库进入可用状态。前者配置这个技能集，而 wizard 为其他一切生成设置路径。它还与 implement 搭配使用：当构建落地一个需要凭据或手动切换的功能时，wizard 会覆盖只有人工才能执行的步骤。当你不确定哪个技能适合当前时刻时，ask-matt 会引导你。