安装此技能
npx skills@latest add mattpocock/skills --skill=wizard 然后在你的编码 agent 里输入 /wizard 。
本页目录
它做什么
wizard 生成一个交互式 bash 脚本，带一个人一步一步走过一段手动流程：接通第三方服务、运行一次性迁移、把一个项目从状态 A 移到状态 B。它会打开每一个 URL，说明点什么、复制什么，捕获返回的内容，并把它写进 .env 文件和 GitHub Actions secret。
agent 写这个脚本；它从不运行脚本。你在自己的机器上运行。一个 wizard 是一个程序，不是一列说明。脚本按顺序运行每一步，并保留你输入的值。你的部分是点击、粘贴、按回车。
什么时候用它
你可以输入 /wizard，agent 也可以自己去拿它。当它撞上一个必须由你走的步骤（stage）——一个它造不出来的密钥、一个它点不了的仪表盘——它给你构建一个 wizard，而不是把说明写进聊天里，让它们滚走。
当下一个挡住你的事情是一趟仪表盘之旅时，就用它：
| 情况 | wizard 会做什么 |
|---|---|
| 一个新开发者需要在应用启动前配置好六个服务 | 按顺序打开每个仪表盘，捕获密钥，写进 .env 和 CI |
| 一次一次性迁移需要按特定顺序打开开关 | 把不可逆的步骤排在确认关卡（confirmation gates）后面 |
| 一个项目必须一次性从状态 A 移到状态 B | 走一遍这个转换，并报告它做不到什么 |
| 你正要把那些步骤写进一份 README | 改为写一个可执行的版本，当某一步过时的时候它会显眼地失败 |
不要用它来决定构建什么；要做那个，grill-with-docs 和 to-spec 才是工具。
前提条件
生成一个不需要任何前提条件。它写出的 wizard 在 bash 上运行，当一个步骤要设置 GitHub secret 或 variable 时，它会使用 gh。如果 gh 缺失或未认证，这次运行不会失败。那个步骤会显示一条警告，而收尾摘要会告诉你需要手工设置什么。
步骤
一个步骤是一个屏幕上的一项聚焦任务。脚本在步骤之间清屏，所以一个溢出屏幕的步骤会丢掉滚走的那部分。你按依赖顺序编写步骤，并设置 TOTAL_STAGES，它驱动进度显示。
这个技能（skill）在写任何脚本之前先界定流程的范围。它读仓库，而不是冷启动发问：.env*、docker-compose*、框架配置，以及 .github/workflows/ 里每一处 secrets.* / vars.* 引用。每一处这样的引用都是 wizard 必须产出的一个值。然后它给你看排好序的步骤列表让你确认。只有在你确认之后，它才把每个步骤映射到一个人实际要走的确切路径（「仪表盘 → 开发者 → API 密钥 → 显示测试密钥 → 复制」）。在它不知道当前 UI 的地方，它会问你或者查文档，而不是编造点击步骤。
对于每一个捕获的值，界定范围（scoping）决定它去哪里：
| 目的地 | 什么时候 |
|---|---|
只有 .env | 本地开发需要它，CI 不需要 |
| GitHub secret | CI 会读它，而且它是敏感的 |
| GitHub variable | CI 会读它，而且它是公开的 |
.env 和 secret 都要 | 本地开发和 CI 都需要它 |
| 哪里都不写 | 这个步骤是一个纯动作：打开一个开关、升级一个套餐 |
模板已经把 UX 解决好了
模板（template） 附带了整套体验：带剩余时间的进度、确认关卡、跨平台打开 URL（包括 WSL）、机密的隐藏输入、幂等的 .env 更新插入、gh secret / gh variable 写入，以及一份收尾摘要，列出它不得不跳过的所有东西。STAGES 标记之上的一切是一个固定的库，在每个 wizard 里都相同，从不手工编辑。因为这个库从不变化，每个 wizard 的行为都一样。每个 wizard 唯一的工作，就是界定流程的范围并编写它的步骤。
写 wizard 的 agent 从不端到端运行它，因为脚本会打开浏览器并等待人工输入。agent 改为静态检查它：bash -n、可用的 shellcheck，以及一趟追踪，确认每个值都落在界定范围所说的地方，并且每个 set_secret 名字都匹配 CI 里一处真实的 secrets.* 引用。所以第一次运行是你的，而那次运行就是测试。
默认用完即弃
| 你有什么 | 该怎么处理脚本 |
|---|---|
| 一次一次性迁移、一套个人配置、一次你永远不会重复的转换 | 把它保存到一个临时路径或 scripts/ 路径，运行它，删掉它 |
| 一条仓库里下一个人也会需要的配置路径 | 提交它，并从 README 链接它，这样他们运行脚本，而不是再问一遍 agent |
常见问题
我的 API 密钥最后会进模型（model）的上下文（context）吗？
不会。agent 写脚本；它不运行脚本。你自己运行脚本，它用隐藏的终端输入捕获密钥，并直接写进 .env 或 gh secret。wizard 是一个 CLI，而模型没有和它连接。这只适用于 wizard 在运行时捕获的值。如果你在界定流程范围时把密钥粘贴进聊天，它就和任何其他粘贴的文本一样，进了上下文。
我能回去改一个我输错的值吗？
运行中途不行。没有后退按钮。步骤向前运行，而在第 3 步答错意味着按 Ctrl-C 再重新运行。重新运行很便宜，因为任何已经写进 .env 的值都会作为默认值提供回来，所以你对那些做对的步骤一路按回车，只重新输入错的那一个。用户在发布周就要求过这个，而它仍然开着：「很喜欢它！不过有一件事，有没有办法回去改你输入过的东西？」
它知道我配置过什么了吗？
部分知道，而且比发布时的反应所假设的要少。它在提问之前先读仓库（你的 .env 文件、docker-compose、框架配置、CI 里的 secrets.* 引用），所以它把范围界定在缺失的值上，而不是像 README 那样从零开始。它不做的是检查第三方服务。如果一个密钥已经存在于你的 .env，wizard 会把它提供回来，按回车就保留它；如果你已经创建了 Stripe 账户但从未保存密钥，wizard 仍然会把你送到仪表盘去拿它。
它在工作流里处在什么位置，在质询（grilling）和规范文档（spec）之后吗？
哪里都不特别。它是一个独立技能（standalone），不是链条上的一步。常见的猜测是 /grill-with-docs → /to-spec → /wizard，那个顺序没问题，但触发器是一段手动流程出现，而那可能发生在任何时刻：你开始之前、构建中途，或者上线很久之后。它也可以当作发现工具。界定范围会在你投入这项工作之前，找出一个任务隐藏的前提条件，比如三个你没想到的 API 密钥。
它在 Claude Code 之外能用吗？
脚本能。它是纯 bash，不管生成它的是哪个运行环境（harness），运行结果都一样。技能本身由模型调用，所以它到处都被列出：在 Claude Code 里输入 /wizard，在 Codex 里输入 $wizard，或者干脆描述你卡住的那套配置。由模型调用也让它可以避开 #693：在那里，Claude 的桌面版和网页版会把用户调用的技能从模型的列表里丢掉，并报告成未安装。
它以前不是由用户调用的吗？
是的。它现在由模型调用，所以当 agent 撞上一个必须由你走的步骤时，它会主动去拿它。你以前能做的事没有一件停止工作。模型调用让 agent 能像你一样调用这个技能，所以 /wizard 的行为一如从前。这个改动修复了一个失败。以前，一个在构建中途撞上凭据墙的 agent 会把六个编号步骤倒进聊天里，让你手工跟着做。现在它会写一个 wizard。
它以前在 in-progress/ 里。现在呢？
engineering/，从 v1.2 起。它从 beta 桶里毕业，现在随插件发布，所以它随其余被晋升的集合一起来，而不需要单独安装。它的行为在毕业时没有变化。
它生效的标志
- 在任何脚本存在之前，你被展示一份排好序的步骤列表、每个步骤产出的值，并被要求确认。
- 每个 URL 都在索要那一页的值之前被打开。你从不需要粘贴一个还没被送去获取的东西。
- 机密是盲打的。没有任何敏感内容回显到你的回滚缓冲区。
- 每个步骤都装得进一个屏幕。你还需要的东西没有滚走。
- Ctrl-C 再重新运行，会从你停下的地方接着来，把已保存的值作为默认值提供。
- 最后的屏幕列出它写了什么，并单独列出它做不到、必须由你手工完成的事。
它在体系中的位置
wizard 是一个随时可用的独立技能，处在自动化停下、必须由人来点击的那条线上。它最近的邻居是 setup-matt-pocock-skills，因为两者都是为了把一个仓库弄到可工作的状态。那一个配置这套技能，而 wizard 为其他一切生成一条配置路径。它也和 implement 配对：当一次构建落地了一个需要凭据或手动切换的功能时，wizard 覆盖只有人才能做的步骤。当你不确定此刻哪个技能合适时，ask-matt 会为你路由。