wp-block-themes

wp-block-themes 技能概览

wp-block-themes 涵盖什么

wp-block-themes 技能主要用于 WordPress 块主题相关工作：theme.json、模板、模板部件、patterns、样式变体，以及最常见的“为什么我的样式没有生效？”这类排查路径。它最适合你需要一个了解文件结构、面向 WordPress 的工作流，而不是只靠通用提示词来处理块主题的时候。

适合哪些人用

如果你正在实现或维护块主题、把经典主题转换为块主题，或者排查 Site Editor 行为，就应该使用 wp-block-themes 技能。它尤其适合设计落地类工作，因为你需要在前端、编辑器和用户自定义样式之间得到可预测的输出。

它为什么不一样

这个技能是决策导向的：它会告诉你先检查什么、哪些文件最关键，以及 WordPress 实际上是如何解析主题设置和用户覆盖的。相比直接让模型“帮我处理块主题”，它更有价值，因为它能减少你对范围、兼容性，以及改动应该放在哪个位置的猜测。

如何使用 wp-block-themes 技能

正确安装并限定作用范围

使用以下命令安装：
npx skills add WordPress/agent-skills --skill wp-block-themes

在进行 wp-block-themes 安装和设置时，先把任务范围限定到当前启用主题的根目录，再开始改动。如果仓库里包含多个主题，先确认准确的主题目录和目标 WordPress 版本，因为 theme.json 的可用特性和行为会随核心版本变化。

提供正确的输入

wp-block-themes 的使用方式在你明确说明以下信息时效果最好：

• 主题根目录或仓库根目录
• 精确的作用面：theme.json、templates/、parts/、patterns/ 或 styles/
• 问题出现的位置：Site Editor、文章编辑器、前端，还是三者都有
• 这是新建实现、主题转换，还是排障

一个高质量提示词可以这样写： “更新当前启用的块主题的 theme.json，让按钮在编辑器和前端都使用新的品牌色，同时保留用户覆盖设置不变。目标 WordPress 6.9。如有需要，检查 template parts。”

先看这些文件

先从 SKILL.md 看起，然后检查：

• references/theme-json.md
• references/templates-and-parts.md
• references/patterns.md
• references/style-variations.md
• references/debugging.md
• references/creating-new-block-theme.md

如果仓库结构不够清晰，也要查看 scripts/detect_block_themes.mjs。wp-block-themes 指南最强的地方在于：先按它的检测步骤确认，再开始编辑。

按正确顺序推进

一个实用的工作流是：

1. 检测主题根目录
2. 确认问题出现在哪个界面
3. 查看对应的参考文件
4. 只修改应该负责这个行为的最小文件
5. 针对用户自定义和缓存过的编辑器状态进行测试

这个顺序很重要，因为很多看起来“坏了”的块主题问题，其实是样式层级或已保存的用户设置问题，并不是主题文件本身有错。

wp-block-themes 技能常见问题

wp-block-themes 只适合高级用户吗？

不是。只要你已经知道自己在编辑哪个主题，并且能清楚描述目标改动，它对新手也很友好。这个技能负责 WordPress 相关的路由判断，但你仍然需要提供主题上下文和期望结果。

什么情况下不该用它？

不要把 wp-block-themes 用在通用的 WordPress 插件工作、块主题之外的 PHP 模板层级排障，或者完全不涉及主题文件的视觉设计任务上。如果你还不确定问题是在主题、用户自定义，还是 Site Editor 里，这也不是它的最佳适用场景。

它和普通提示词有什么区别？

普通提示词可能会在不检查主题文件系统、兼容范围或块主题文件位置的情况下直接建议修改。wp-block-themes 技能更适合你需要有纪律地处理 wp-block-themes usage，覆盖 theme.json、模板、部件和样式的情况，尤其是在设计落地这类“文件放对地方”很关键的工作中。

通常是什么阻碍采用？

最常见的阻碍是主题范围不清、没有明确 WordPress 版本目标，以及混淆主题默认值和用户选定样式。如果这些信息一开始答不上来，技能依然能帮你，但第一轮结果可能不会那么精确。

如何改进 wp-block-themes 技能

提供更强的设计输入

如果你想获得更好的 wp-block-themes for Design Implementation 结果，请明确写出设计意图和受影响的区块或区域。比如，与其说“让主题看起来更清爽”，不如说“为所有模板设置默认的 heading 间距和按钮圆角”。前者可执行，后者会迫使模型去猜需求。

把默认值和覆盖值分开说明

一个常见失败模式，是以为 theme.json 的改动可以覆盖用户自定义设置。如果问题其实出在已保存的 global styles 或已选中的 style variation 上，就要直接说明。想提升结果时，请明确你要的是：

• 主题默认值
• 编辑器控制项
• 样式变体
• 单次模板改动

用最小的失败样例继续迭代

如果第一次输出已经接近，但还不对，就把下一轮请求缩小到一个文件和一个症状。比如：styles/blue.json 已被选中，但重载后没有反映出来；说明这是否符合预期，以及应该测试什么。这样比泛泛要求重做整个设计更有助于排障。

按仓库约定做校验

在编辑前先确认仓库是否使用 patterns、样式变体，或者是否只是一个最小主题脚手架，wp-block-themes 的效果会更好。如果第一次结果显得很泛，再带上仓库文件路径、当前启用主题名称，以及你希望应用的具体参考文件重新运行。