wp-block-themes 是一个面向 WordPress 区块主题开发的技能，属于 Automattic 的 agent-skills 仓库。它适用于编辑 theme.json（预设、设置、样式、按区块样式）、添加或修改模板（templates/.html）与模板部件（parts/.html）、添加图案（patterns/.php）并控制其在插入器中显示的内容、添加样式变体（styles/.json），以及调试“样式不应用”或“编辑器不反映 theme.json”等问题。
使用该技能前需要明确：仓库根目录以及目标主题（若存在多个主题，需指定主题目录）；目标 WordPress 版本范围（theme.json 版本和功能随核心版本变化）；问题出现的场景（站点编辑器、文章编辑器、前端或全部）。
该技能提供了一套操作流程。首先进行分诊与定位区块主题根目录，运行 node skills/wp-project-triage/scripts/detect_wp_project.mjs 进行项目分诊，再运行 node skills/wp-block-themes/scripts/detect_block_themes.mjs 检测主题根目录与关键文件夹；若存在多个主题，选择一个并将所有更改限定在该主题根目录内。
如需创建新的区块主题（或从经典主题转换），建议从已知良好的脚手架开始，或从 WordPress 环境导出，而不是猜测文件布局；同时需明确最低支持的 WordPress 版本，因为 theme.json 模式版本不同。创建主题根目录后，重新运行 detect_block_themes 并继续后续步骤。
确认主题类型与覆盖预期时，区块主题的标志是存在 theme.json，以及存在 templates/ 和/或 parts/。需记住样式层级：核心默认 → theme.json → 子主题 → 用户自定义；用户自定义可能使 theme.json 的修改看起来被“忽略”。
修改 theme.json 时，需区分是更改设置（UI 允许的内容：预设、排版比例、颜色、布局、间距）还是样式（默认外观：元素/区块的类 CSS 规则）。
模板位于 templates/ 下，为 HTML 文件；模板部件位于 parts/ 下，且不得嵌套在子目录中。图案方面，若希望主题拥有图案，优先使用 patterns/ 下的文件系统图案。样式变体是 styles/ 下的 JSON 文件；注意一旦用户选择了某个样式变体，该选择会存储在数据库中，因此更改文件可能不会自动“更新用户所见”。
验证时需确认站点编辑器在预期位置（样式 UI、模板、图案）反映更改，前端以预期样式渲染；若样式未变化，确认用户自定义是否覆盖了主题默认值；若涉及资源（字体、自定义 JS/CSS 构建），运行仓库的构建/检查脚本。
常见失败模式包括：主题根目录错误（编辑了未激活的主题）、用户自定义覆盖默认值、theme.json 形状无效或拼写错误导致无法应用、模板/部件放错文件夹（或部件嵌套）。若上游行为不明确，可查阅 Theme Handbook 和 Block Editor Handbook 中关于 theme.json、模板、图案和样式变体的权威文档。