v1.2：/wait-what、/writing-for-agents、Claude Code 插件等更新
我的技能集 1.2 版本已经发布。本次发布把这些技能打包成 Claude Code 插件，为每个技能添加了 Codex 元数据，并在 aihero.dev/skills 上提供完整文档。插件新增三个技能、重命名一个技能，并移除了六个技能。
完整变更记录见 v1.2.0 发布说明。本文重点介绍这些变化会怎样影响你。
为每个技能添加 Codex 元数据
每个 SKILL.md 旁边现在都有一个 agents/openai.yaml。这个伴随文件保存 Codex 的 UI 元数据（interface.display_name、interface.short_description），因此同一套技能无需生成副本，就能同时用于两种智能体运行环境。
该文件中最重要的一行是 policy.allow_implicit_invocation: false。它相当于 Codex 版本的 disable-model-invocation: true。现在，每个只能由用户调用的技能都带有这项设置；在你输入 $skill 之前，Codex 不会把它放进智能体上下文。本次发布前，用户调用与模型调用的区分只在 Claude Code 中成立，在 Codex 中并未生效。
AGENTS.md 是指向 CLAUDE.md 的符号链接，因此 Codex 会读取同一份仓库指令。
aihero.dev/skills 文档站
从 /skills 开始浏览各个分组。主流程依次是 /grill-with-docs → /to-spec → /to-tickets → /implement → /code-review。左侧面板则提供所有技能的完整索引。
每个页面都有常见问题和做到以下就算成功两个部分。常见问题来自大家实际向我提出的问题所组成的 wiki。术语首次出现时会链接到 AI 编码词典；例如，ticket 链接会指向我对“任务”的定义。你既可以通过这些文档学习技能，也可以借此理解 AI 编码的工作方式。
破坏性变更： /writing-great-skills → /writing-for-agents
请使用新名称重新安装。旧名称没有别名，已经彻底移除。
这次重命名反映了范围的扩大。该参考资料现在覆盖智能体会读取的任何文档，包括技能、AGENTS.md、CLAUDE.md，以及通过上下文指针访问的文档，而不再只针对技能。你可以用它把负担过重的 AGENTS.md 拆成多个技能，避免在会话开头一次性塞入过多上下文。
它同时带来三项结构调整：
GLOSSARY.md已合并进SKILL.md，每个术语只保留一份权威说明。- 技能专属机制（frontmatter、模型调用与用户调用、路由技能、调用边界）移至
SKILL-MECHANICS.md。 - 该技能由模型调用。当你创建或编辑技能，或修改
AGENTS.md/CLAUDE.md时，它会自动触发。
精简章节新增了一个术语：缓存。环境本身就是事实来源，例如 package.json 脚本、配置文件、目录结构和 --help 输出。把这些内容重新写进文档，本质上只是缓存了一次查询；只有查询成本较高时，这份缓存才值得加载。应该缓存智能体无法直接查到的内容：未写明的约定、某项选择背后的原因、配置文件不会暴露的边界情况。至于查看一个文件或运行一条命令就能得到的信息，应留在环境中现查现用，这样才不会过期。
新增： /wait-what
这是一个只用一个词纠正模型啰嗦问题的技能。当某条回复没有让你听懂时，立刻输入它。智能体会换一种说法：补充少量上下文，使用 ASD-STE100 简化技术英语，并采用 CONTEXT.md 中的统一语言。它由用户调用，全文只有三行。
它的机制就在名称本身。要求简洁的技能往往越写越长——即使写到 400 行，模型依然可能很啰嗦——所以这个技能只保留一个精确的引导词，没有其他内容。用输出形式来命名（如 /tldr、/no-fluff）会让模型机械删词，反而更难理解；用听者的状态来命名，则会同时表达两项需求：减少文字，并补上你缺失的上下文。
它只修复当前这一条回复，不能保证下一条不再出现同样的问题。解决术语障碍的根本方法，是提前通过 /grill-with-docs 建立共享语言；在这套语言尚未建立时，再使用 /wait-what。
新增： /wizard
/wizard 已从 in-progress/ 毕业，进入工程分类，并改为由模型调用。
它会生成一个交互式 Bash 脚本，引导人类完成手动流程、第三方服务设置、一次性迁移或 A→B 状态切换。脚本会打开每个网址、说明需要点击哪里、接收你粘贴的值，并把它们写入 .env 文件和 GitHub Actions secrets。由于运行的是确定性脚本，你输入的任何秘密都不会传给智能体。
随附的 template.sh 已经解决了交互体验问题：显示进度和剩余时间、设置确认门、跨平台打开网址（包括 WSL）、隐藏秘密输入、幂等更新 .env、以可降级方式写入 gh secret / gh variable，并在结束时汇总跳过的步骤。STAGES 标记以上的内容是固定库，绝不手动编辑；技能只负责界定流程范围并编写各个阶段。
改为模型调用后，智能体一遇到只有人类才能完成的步骤，就会使用 /wizard，而不是把一串编号说明丢进聊天。手动输入 /wizard 仍与以前完全一样。技能描述列出了四类触发场景：供给基础设施、设置凭据或 CI secrets、操作陌生的第三方控制台，以及一次性迁移或切换；同时明确了一项不触发条件：智能体自己能完成的步骤，不要调用它。智能体能做的工作，就应该由智能体完成。/wizard 专门处理那些你不会交给智能体的点击、批准和控制台操作。
新增： /to-questionnaire
/to-questionnaire 已从 in-progress/ 毕业，进入效率分类。
它会把一个你无法独自回答的决策，转换成一份 Markdown 问卷，交给真正能回答的人。对方可以异步填写，也可以在会议中共同完成。我是在一次规划花园办公室的 /wayfinder 会话中做出它的：智能体正在追问我，但真正应该询问的人是我的妻子。于是问卷被放进 Google 文档，我们一起逐项完成，再把答案交还给智能体。
它最关键的做法，是围绕问卷如何交付来追问你，而不是追问主题本身。普通的 Grilling 会话会深入盘问主题，但这里的问题恰恰是你无法回答主题。因此，访谈只询问问卷要交给谁、你希望拿回什么，再让所有问题都对准这两者之间的信息缺口。
/ask-matt 把它定义为 /grill-me 的反向操作：挖掘别人，而不是挖掘你自己。
变更： /grilling 改为分轮提问
/grilling 从每次只问一个问题，改为按轮次提问。同样的 13 个问题，现在大约 3 轮即可完成，而不再需要 13 个来回。
该技能把工作绘制成一棵设计树：每项决策都会分叉出依赖它的后续决策。前沿由所有前置条件已经确定的决策组成，也就是现在可以提出、无需猜测尚未获得答案的问题。技能会把整个前沿作为一轮编号问题提出，再根据你的回答重新计算前沿并进入下一轮。如果某个问题依赖另一个尚未解决的问题，它就会留到后续轮次。当前沿为空时，会话结束。
环境能够回答的事实问题会交给子智能体，因此研究不会阻塞整轮提问。正在进行的探索会被视为尚未解决的前置条件：只有依赖它的问题需要等待，前沿中的其他问题仍会立即提出。所有决策仍由你作出。
每轮中的所有问题都使用固定格式：
❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>➡️ <your recommended answer>
每一轮都是便于扫读的编号列表，每条建议都与对应问题分开。你可以按编号作答（“Q1 同意，Q2 同意，Q3 改成这样”），非常适合语音口述。
/grill-me、/grill-with-docs 和 /triage 现在也会逐轮推进前沿。如果仍想一次只回答一个问题，退出方式不变：在全局 CLAUDE.md 中加入一行说明。
/grilling 的措辞也改得更通用：“这项计划”改为“这件事”，“执行计划”改为“采取行动”，“探索代码库”改为“探索环境”。方法本身没有变化，但现在可以用来压力测试任何计划、决策或想法。
变更： /prototype 生成一个可共享的 HTML 文件
逻辑原型分支现在不再生成终端应用，而是生成一个完全自包含的文件：纯 HTML、CSS 和 JavaScript，无需构建，也无需服务器。非开发者双击即可打开，并使用自己的领域语言操作：带标签的状态面板、始终可用的自由操作按钮，以及分页显示的引导式演练；每个演练都是一个场景，下面按顺序排列操作按钮。可移植的纯逻辑模块仍可迁入正式代码，真正可丢弃的是外层 HTML 壳。
“可丢弃”不再意味着必须删除。/prototype 的输出会作为可运行的证据，保存在从主分支分出的 prototype/<name> 分支上，并在实现任务中留下指向它的上下文指针。主分支只保留经过验证的决策，而探索过程依然可以找到。最终答案（结论加问题）仍会记录在任务、ADR 或提交中。
变更： /wayfinder 任务改为决策任务
人们往往把 /wayfinder 的 ticket 理解为普通实现任务，也就是需要执行的一段构建工作。但 /wayfinder 使用的是决策任务：解决结果是一项决策的问题。技能描述、开场说明、README 简介和文档页面现在都会先介绍这个术语。术语建立后，日常行文仍简称为“任务”，而 CONTEXT.md 会把决策任务记录为领域术语。
研究任务不再被搁置到单独会话中。研究仍是一种真正的任务类型，因为它确实是下游决策共同依赖的阻塞项；变化的是解决方式。研究可以 AFK 运行，因此绘图过程不会停下来等待阅读结果：创建任务后，绘图会话会为每个研究任务启动一个 /research 子智能体并行完成，并把发现记录在 research/<name> 分支上，同时留下上下文指针。研究任务是“一次会话只处理一个任务”规则的唯一例外。
变更： /ask-matt routing
路由器新增了阶段边界。阶段是一次会话中的一段工作，例如追问、实现或 QA；两个阶段之间的边界，就是决定如何处理已积累上下文的时刻。原来只有两项的说明，现在变成一棵按顺序列出五种选择的决策树：继续、/clear、/handoff、子智能体、/compact。具体理由写在 PHASE-BOUNDARIES.md 中，同时还修复了三个问题：
/handoff过去被说得过于万能。它的适用范围其实很窄：只有当信息必须“转移”到新的运行环境、新目录、同事，或阶段中途分叉出的支线任务时，才需要它。/compact是兜底选项，而不是第一选择。它位于决策树最底部。一上来就使用它，会让新会话对摘要压平、丢失的内容产生错误却自信的理解。- 以前缺少两个分支。首先应该判断能否继续当前会话，因为这是唯一能把对话本身保留为一手来源、而不是把它变成摘要的方法。范围足够明确、可以 AFK 运行的工作，则交给子智能体。
上下文卫生中的逃生选项现在从 /handoff 改为 /compact，聪明区的参考值也从约 120k Token 调整为约 150k Token。
/wayfinder 的路由修复了人们使用这套重量级流程时最常犯的两个错误。使用范围过宽：/wayfinder 比一次普通 Grilling 更慢、信息更密集，因此只适合真正无法装进一次会话的想法；范围明确的功能应该使用 /grill-with-docs。交接时迷失方向：地图梳理清楚后，/wayfinder 负责交接，而不是直接构建。此时应在 /to-spec 汇入主流程，把地图中相互链接的决策压缩成可构建的计划；只有工作量最终确实很小时，才直接进入 /implement。
/grilling 和 /resolving-merge-conflicts 过去没有出现在路由器中，现在已经补上。/grill-me 与 /grill-with-docs 的分流依据，则是当前是否位于工作目录中。
变更：其他小项
/improve-codebase-architecture在 Explore 步骤新增了 YAGNI 范围过滤器，不再平均扫描整个仓库。你指定方向，它就沿该方向探索；如果没有指定，它会读取最近约 20 条提交信息，把探索重点放在活跃开发的路径上。没人触碰的代码即使存在加深模块的机会，也只是永远无法兑现收益的重构，因此报告不再整理这些休眠角落。/setup-matt-pocock-skills现在更友好。只有安装了/triage时才会询问分诊标签，而且只问一个默认建议“是”的问题。不再询问是否把外部 PR 作为请求入口，该开关默认关闭。除非仓库显现出 monorepo 特征，领域文档默认采用单一上下文。本地 Markdown 任务会按“一项任务一个文件”保存到.scratch/<feature>/issues/<NN>-<slug>.md，规格文件则为spec.md。/to-prd→/to-spec的重命名已经完成。发布内容中只保留“Spec”这一术语。/to-spec删除了“你可能把它称为 PRD”的开场说明，/code-review改为引用来源任务或规格，GitHub 和 GitLab 的跟踪器模板也不再把“PRD”写进每个使用它们的仓库。
移除：六个技能
这六个技能都不在 Claude Code 插件中，但此前都可以通过 skills.sh 安装；skills.sh 会提供仓库里的所有技能。其中四个已被功能更完善的技能吸收：
/ubiquitous-language→/domain-modeling：后者维护完整领域模型，而不是从一次对话中导出一份词汇表。/design-an-interface→/codebase-design。功能没有丢失：design-it-twice 方法已经作为DESIGN-IT-TWICE.md包含在该技能中。/qa→/triage和/to-tickets。/request-refactor-plan→/to-spec和/improve-codebase-architecture。
另外两个从来只是我个人使用，并绑定到我自己的机器。personal/ 分类也随它们一同移除：/edit-article 和 /obsidian-vault。
skills/deprecated/ 会作为空分类保留。skills/in-progress/ 不变，并明确说明了它的真实定位：这是一个有意公开的 Beta 渠道，可以通过 skills.sh 每次安装一个技能。