AI Skills - Waza：为什么

关于环境：Waza 最初是为 Claude Code 设计的技能包，本系列的演示环境是 OpenCode（开源的 AI 编程终端）。Waza 的技能在两个工具中都能正常工作，差异主要体现在配置路径和插件机制上。

问题：AI 的输出缺结构

如果你用过 Claude Code 一段时间，大概会遇到这样的情况：让 AI 改一个 bug，它改了三个文件，引入了两个新问题，还顺手重构了一个没让你改的函数。不是模型不够聪明，而是没有人告诉它"你这次的任务边界在哪里"。

这是 Waza 要解决的核心命题。AI 在原始输出能力上远超人类，但它的输出默认是扁平的、不分层级的——它不知道什么时候该停下来想，什么时候该写代码，什么时候该审查。缺少的就是这一层结构。

作者 tw93 在 "You Don't Know Claude Code" 这篇文章里提出了一个六层框架来理解 Claude Code 的完整能力：

Waza 实现的就是第三层——Skills 层。它不替代 CLAUDE.md，不替代 MCP 工具，不替代 hooks。它只做一件事：给 AI 一套清晰的方法论，在需要的时候加载，用完就退出。

克制原则

Waza 最核心的设计哲学用一句话就能说清楚：

Every rule the author writes becomes a ceiling.

你写的每一条规则都会成为 AI 能力的天花板。规则越多，天花板越低。这是 Waza 和很多同类项目最根本的分歧。

作者对此有明确的判断——模型在快速变强，今天需要 200 行 prompt 才能约束的行为，六个月后可能 20 行就够了。如果在今天写死了太多规则，六个月后这些规则不仅不再必要，反而会限制模型发挥更好的能力。

所以 Waza 的策略是：每个技能只设目标和关键约束，然后放手。不写死行为细节，不给模型戴太多镣铐。随着模型能力的提升，这种克制的策略会获得复利式的回报。

具体来说，一个好的技能在 Waza 的标准里是这样的：

• 明确的触发条件（什么时候该用这个技能）
• 清晰的执行路径（进了技能后怎么做）
• 确定的退出信号（做完后停下来，不自动做下一件事）
• 描述词短到刚好够模型识别（9 个 token 而不是 45 个）

不做的事同样明确：不自动连锁调用、不替模型做判断、不把参考材料塞进 SKILL.md 正文。

为什么不是 Superpowers / gstack

市面上已经有同类项目，最出名的是 Superpowers 和 gstack。Waza 和它们的区别在于设计取向上：

Superpowers 提供了大量预置技能，覆盖的场景非常广，安装后立即可用的东西很多。但代价是技能数量多、配置项多、学习曲线陡。更重要的是，每一条预置规则都可能成为模型能力的上限，整个体系偏"重"。

gstack 则走另一个极端——高度集成、高度自动化，适合那些想要完整工作流一键配置的团队。但如果你的需求不在它的预设路径里，改起来会很痛苦。

Waza 的选择：8 个技能，不多不少。覆盖的是工程师最核心的 8 个习惯——想、设计、审查、调试、写作、学习、阅读、健康检查。每个技能只做一件事，不做大而全的 workflow engine。不追求"装完就能用所有场景"，追求"每个技能在它该出现的时候都可靠"。

这种选择的直接结果是 Waza 的安装很轻——npx skills add tw93/Waza 一行命令，全局生效。不需要读长篇文档才能开始用。

从真实失败中长出来

Waza 的每个技能末尾都有一张 Gotchas 表。这些不是理论推导出来的最佳实践，是真实事故的记录。

举几个例子：

• /think 技能的 gotcha："Moved files to ~/project, repo was at ~/www/project"——在没有确认工作目录的情况下开始操作，文件搬错了地方。解法：pwd 必须先于任何文件操作。
• /check 技能的 gotcha："Commented on #249 when discussing #255"——审 PR 的时候弄混了 issue 编号。解法：gh issue view N 先确认标题再行动。
• /design 技能的 gotcha："Three cards, identical shadows, identical padding — a template"——三张卡片看起来一模一样，换内容不需要改布局。解法：如果交换内容不需要调整布局，重做。
• /hunt 技能的 gotcha："Patched client pane instead of local pane"——修错了地方，因为没有先回溯执行路径。解法：碰任何文件之前，先回溯执行路径。

作者明确说："30 days, 300+ sessions, 7 projects, 500 hours." 这些 gotcha 就是从 500 小时的实战里一条一条捞出来的。每个 gotcha 都对应一次让人头疼的 debug 经历。

这也是 Waza 和纯理论技能包的本质区别——它不是在办公室里设计出来的"最佳实践"，是在真实项目里撞出来的"下次别再犯"。

每个技能只做一件事

最后一点——单一职责。Waza 的每个技能只有一个目标，描述词里写得清清楚楚：

• /think 是 "Turns rough ideas into approved plans"——不做实现
• /hunt 是 "Finds root cause before applying any fix"——不做 review
• /write 是 "Strips AI writing patterns"——不润色词汇，不做结构重组
• /learn 是 "From raw materials to published output"——不做 quick lookup

如果你在一个技能里描述了三件不同的事情，模型就会在错误的时候触发它。Waza 用"Not for"排除句明确划界。比如 /think 的 "Not for bug fixes or small edits"，/hunt 的 "Not for code review or new features"。

这种纪律保证了 8 个技能各司其职，不会在同一个 session 里互相打架。

下一篇是这个系列的最后一篇——怎么用 Waza。深入 8 个技能的实际用法、连锁调用工作流、以及如何用 Waza 写完这篇博客本身。