本页内容
它的作用
wizard 生成一个交互式 bash 脚本，逐步引导一个人完成手工流程——接第三方服务、跑一次性迁移、把项目从状态 A 移到状态 B。它打开每个 URL，说要点什么、复制什么，捕获返回的内容，并把它写进 .env 文件和 GitHub Actions 密钥。
这个 agent 写脚本；它从不运行脚本。由你在自己的机器上运行。所以 wizard 不是一份你照做的指令清单——它是一个驱动流程并持有状态的小程序，而你的部分只是点击、粘贴和按回车。
深入阅读： 加入「为真正的工程师打造的 AI 编码」候补名单
何时使用
你可以输入 /wizard，而且智能体也可以自行调用它。当它遇到需要你完成的步骤——一个它无法铸造的密钥、一个它无法点击的仪表盘——它会为你构建一个 wizard，而不是把指令写进对话里任其滚走。
当阻塞你的下一件事是穿越一个仪表盘时使用它：
| 情境 | wizard 做什么 |
|---|---|
| 一个新开发者在应用启动前需要配置六个服务 | 按顺序打开每个仪表盘，捕获密钥，把它们写入 .env 和 CI |
| 一次性迁移需要按特定顺序拨动开关 | 把不可逆的步骤排在确认门之后 |
| 一个项目需要从状态 A 一次性移动到状态 B | 走完转换，报告做不到的部分 |
| 你正要把这些步骤写进 README | 改为写一个可执行版本，它不会那么安静地腐烂 |
不要用它来 decide 构建什么；为此， grill-with-docs and to-spec 就是工具。
前置条件
生成它无需任何前置。它写的 wizard 在 bash 上运行，并使用 gh 当某个阶段设置 GitHub 密钥或变量时。如果 gh 缺失或未认证，该阶段会变成警告，收尾摘要会告诉你手动设置什么，而不是让运行失败。
阶段
A stage 是一个屏幕上一个专注的任务。脚本会在阶段之间清空终端，所以溢出屏幕的阶段会丢失滚走的部分。你按依赖顺序编写阶段，并设置 TOTAL_STAGES，它驱动进度显示。
范围界定在任何一行写出之前发生。 skill 读取仓库，而不是冷提问： .env*, docker-compose*，框架配置，以及每个 secrets.* / vars.* 在 .github/workflows/ ——这些每一个都是 wizard 必须产出的值。然后它展示有序阶段列表供你确认，之后才把每个阶段映射到人类遵循的确切路径（「仪表盘 → 开发者 → API 密钥 → 显示测试密钥 → 复制」）。在它不知道当前 UI 的地方，它会问你或查文档，而不是编造点击。
对于每个捕获的值，范围界定决定它落在哪里：
| 目的地 | 何时 |
|---|---|
.env only | 本地开发需要它，CI 不需要 |
| GitHub 密钥 | CI 会读取它，而且是敏感的 |
| GitHub 变量 | CI 会读取它，而且是公开的 |
两者 .env 和一个密钥 | 本地开发与 CI 都需要它 |
| 哪里都不 | 阶段是纯粹的动作——拨动开关、升级计划 |
模板已经解决了用户体验
这个 template 自带完整体验：带剩余时间的进度、确认门、包括 WSL 的跨平台 URL 打开、密钥隐藏输入、幂等的 .env upsert， gh secret / gh variable 写入，以及一份关于它不得不跳过之物的收尾摘要。 STAGES 标记是一个固定库，在每个 wizard 中都相同，绝不经手编辑。一致性就是重点。你的工作只是界定流程范围并编写它的阶段。
写 wizard 的智能体从不端到端运行它，因为它会打开浏览器并等待人工输入。它改为静态验证： bash -n, shellcheck 在可用处，以及每个值都落在范围界定所说之处的追踪，连同每个 set_secret 名字匹配真实的 secrets.* 中的参考。相应地设好你的预期——第一次运行是你的，而那次运行就是测试。
默认即短暂
| 你手头有什么 | 怎么处理脚本 |
|---|---|
| 一次性迁移、个人配置、永远不会重复的过渡 | 把它保存到临时或 scripts/ 路径，运行它，删除它 |
| 仓库里的下一个人也会需要的配置路径 | 提交它并从 README 链接它，这样他们运行脚本，而不是重新问智能体 |
常见问题
我的 API 密钥会进入模型的上下文吗？
不。智能体写脚本；它不运行脚本。脚本由你自己运行，它以隐藏终端输入的方式捕获密钥，并直接写入 .env or gh secret。wizard 是一个 CLI，模型并未与它相连。一个提醒：这对 wizard 在运行时捕获的值成立。如果你在梳理流程时把密钥粘贴到对话里，它就在 context 就像其他粘贴的文本一样。
我能回去修改打错的某个值吗？
运行中途不行。没有返回按钮——阶段向前推进，第 3 阶段答错就意味着 Ctrl-C 重跑。重跑按设计很便宜：任何已写入 .env 会被作为默认值回显，所以你对正确的阶段直接按回车，只需重新输入错误的那一个。这个问题在发布周就被提出，至今没有关闭：「超喜欢！不过有一件事——有没有办法回去修改我输入的内容？」
有一个相关的开放 bug。 ask 提示词插入 ^[[D / ^[[C 而不是移动光标，因为提示词使用 read -r 而不是 Readline（issue #741）。退格键有效；方向键无效。请删回到出错处，而不是把光标移进错误里。
它知道我已完成什么配置吗？
部分，而且比发布时的反应所假设的要少。它在提问前先读取仓库——你的 .env 文件， docker-compose，框架配置、 secrets.* 在 CI 中的引用——所以它限定到真正缺失的值，而不是像 README 那样从零开始。它不做的是检查第三方服务。如果密钥存在于你的 .env wizard 会把它回显，按回车保留；如果你已创建 Stripe 账户但从没保存过密钥，wizard 仍会带你去仪表盘拿它。
它在工作流中处于什么位置——在审问和规格说明之后？
没有特别的位置。它是独立的，不是链上的一步。常见的猜测是 /grill-with-docs → /to-spec → /wizard，这样也可以，但触发条件是一个随时可能出现的人工流程：开工前、构建中或发布后很久。它也是一个发现工具——在投入工作之前，范围界定会暴露任务的隐藏前置条件，比如你还没想到的三个 API 密钥。
它在 Claude Code 之外能工作吗？
产物可以，无条件地：它是纯 bash 脚本，不在乎 运行框架 生成它。技能本身由模型自动调用，所以它到处都在列表里——输入 /wizard 在 Claude Code 或 $wizard 在 Codex 中，或直接描述你卡住的配置。由模型自动调用也让它远离 #693，Claude 桌面端和网页端会丢弃 user-invoked 来自 model的列表并把它们报告为未安装。
这个以前不是由用户调用的吗？
确实如此。它现在由模型自动调用，所以智能体在遇到需要你完成的步骤时会主动调用它。你以前能做的都没有失效——模型自动调用 adds 智能体的能力范围，它从不拿走你的，所以 /wizard 行为与以前完全一样。改变的是它消除的失败模式：智能体在构建中途撞上凭证墙，然后把六个编号步骤倒进对话里让你手动跟随。
它以前在 in-progress/ ——它现在在哪？
engineering/，自 v1.2 起。它已从测试桶毕业，随插件一起发布，与其余正式版技能一同到来，无需单独安装。毕业时其行为没有改变。
做到以下就算成功
- 你被展示一份有序的阶段列表和每个阶段产出的值，并被要求确认——在任何脚本存在之前。
- 每个 URL 都会在被索要页面上的值之前打开。你永远不会被要求粘贴自己没被派去取的东西。
- 密钥盲输。没有敏感内容回显到你的滚动记录中。
- 每个阶段都适配一个屏幕。你还需要的内容不会滚出视野。
- 按 Ctrl-C 后重新运行会从上次中断处继续，把已保存的值作为默认值提供。
- 最终屏幕列出它写的内容，并单独列出它做不到、需要你手动完成的部分。
在流程中的位置
wizard 是一个随时可调用的独立技能，坐在自动化停止、必须由人来点击的那条线上。它最近的邻居是 setup-matt-pocock-skills，因为两者都是为了让仓库进入可工作状态——那一个配置这套技能，而 wizard 为其他一切生成配置路径。它还与 implement：当一次构建交付的功能需要凭证或人工切换时，wizard 就是完成人类那一半的方式。当你不确定此刻该用哪个技能时， ask-matt 为你指路。