1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | wp-block-themes（WordPress 官方 Agent Skills 合集子技能） | GitHub API |
| 作者/维护者 | WordPress.org 官方项目账号；子目录由 Automattic、rtCamp、XWP 三家机构员工共同维护 | GitHub API |
| 来源链接 | https://github.com/WordPress/agent-skills/tree/trunk/skills/wp-block-themes | — |
| 许可证 | GPL-2.0-or-later（仓库 LICENSE 文件明确写明） | 网页抓取（LICENSE 原文） |
| GitHub Stars / Forks | 1,952 / 288（整个合集仓库口径，覆盖 18 个子技能） | GitHub API |
| 最新版本 | README 自评 “v1”，无正式 Git Release/Tag | 网页抓取（README） |
| 安装方式 | npx skills add 单命令安装 / 仓库脚本批量安装 / 手动复制目录 |
网页抓取（README） |
2. 功能介绍与亮点
覆盖 WordPress 区块主题（Block Theme）开发全流程：theme.json 全局设置与样式管理（配色、排版、间距等预设及每区块样式）、模板与模板部件（templates/*.html、parts/*.html）、区块图案（patterns/*.php）及其在插入器中的呈现控制、样式变体（styles/*.json）管理，以及 Site Editor 常见故障排查（样式优先级层级、覆盖规则、缓存问题）。配套 6 篇专题参考文档（新建区块主题、调试排错、theme.json 详解、模板与部件、图案、样式变体）与 1 个纯本地文件系统扫描的检测脚本 detect_block_themes.mjs，可自动定位仓库内的主题根目录并判断其是否为区块主题。
技能正文特别提醒一个容易踩坑的机制：用户一旦在前台 Site Editor 中选择了某个样式变体，该选择会被写入数据库，之后仅修改样式变体文件本身可能不会反映到用户实际看到的效果——这正是“改了 theme.json 却看不到变化”这类常见困惑的根源。README 公开披露技能文本由 GPT-5.2 Codex 基于官方文档生成、再经 WordPress 贡献者人工审核编辑。同一仓库另有 17 个姊妹技能覆盖区块开发、插件架构、REST API、可访问性等 WordPress 全栈场景，可搭配安装。
3. 适用场景
固定分类：前端与设计。适用于 WordPress 主题开发者、区块主题作者，以及使用 Claude Code、Codex 等 AI 编程助手做 theme.json 全局样式配置、模板/模板部件编写、区块图案设计的初中级开发者——尤其能帮助排查“Site Editor 里改了样式却不生效”这类因样式优先级（核心默认 → theme.json → 子主题 → 用户自定义）与数据库覆盖机制导致的常见困惑。
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持——官方 README 专门列出
.claude/skills/项目级与全局两种安装路径 - Codex：✅ 原生支持——
.codex/skills/专属路径，仓库安装脚本多处以 Codex 为目标之一 - OpenClaw：⚠️ 未见专门验证——README 明确列出的目标客户端为 Claude Code、Cursor、Codex、VS Code Copilot、Antigravity，未点名 OpenClaw；可经通用第三方安装器（
npx skills add）安装，但仓库自身文档未专门测试 - Hermes Agent：⚠️ 同上，未见专门验证
5. 推荐理由
WordPress 官方项目账号亲自下场，把区块主题开发中 theme.json 配置、模板与样式变体管理、Site Editor 排错的实战经验打包成可直接安装给 AI 编程助手使用的技能包，帮助 AI 助手准确处理 WordPress 特有的样式优先级与数据库覆盖机制，避免生成“改了文件却不生效”的无效建议。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 子目录本身由 Automattic、rtCamp、XWP 三家机构员工共同提交维护；另有独立开发者 sandk0 提交真实 bug 报告、Inpsyde 机构工程师 widoz 反馈兼容性问题、XWP 工程师 Mikey Arce 提交改进 PR——多个独立来源的真实使用反馈，但尚无专门的官方新闻报道或大规模第三方讨论 |
| 可用性 | 9 | 一条 npx 命令即可安装；6 篇专题参考文档 + 1 个纯本地检测脚本，覆盖新建/排错/theme.json/模板/图案/样式变体全流程；子目录最近一次提交在 2026-07-27，近期仍在维护；WordPress 核心免费，无付费依赖 |
| 安全性 | 9 | 唯一脚本 detect_block_themes.mjs 为纯本地文件系统扫描（仅 fs.readdirSync/fs.statSync），无网络请求、无远程代码执行；GPL-2.0-or-later 许可证在 LICENSE 文件中明确写明；官方项目账号出品，全部内容开源可审计，未发现可疑指令 |
综合评分（三项均值）：8.3
7. 跟同类 Skills 相比的优势
| 竞品 | 定位 | 与本技能的差异 |
|---|---|---|
| Create Block Theme（WordPress.org 官方插件） | 通过 wp-admin 后台图形界面导出/创建区块主题 | 依赖手动点击后台 UI 完成操作，不在 AI 助手对话内直接编辑代码或解释样式优先级排错逻辑 |
| WordPress Block Editor Handbook（官方静态文档） | 网页形式的 theme.json 参考手册与全局样式说明 |
需要开发者自行阅读检索、手动比对项目代码，不含自动检测脚本，也不会在排错时主动定位问题 |
| Automattic/wordpress-agent-skills | 实验性原型集合，专注“用自然语言描述直接生成整站主题并部署到本地 Studio 站点”，官方自述“早期阶段” | 聚焦一键生成整站原型，而非教 AI 助手正确编写与排查已有主题的 theme.json/模板/样式变体 |
| sirreal/agent-skills（wordpress-trac 子技能） | 个人 WordPress 核心贡献者维护，服务于 Trac 工单查询、核心提交信息撰写 | 面向 WordPress 核心贡献者的内部协作场景，与面向主题开发者的区块主题教学完全不重叠 |
8. 用户评价
GitHub 仓库 issue 区可查证到独立开发者 sandk0 提交的真实问题反馈（#86）：按文档做全局安装后，技能脚本以工作目录相对路径调用，导致从 WordPress 项目目录执行时第一步就找不到文件，该问题已被官方标记跟进；Inpsyde 机构工程师 widoz 通过 issue（#16）反馈 compatibility 字段在部分 AI 客户端下会触发兼容性警告；XWP 机构工程师 Mikey Arce 提交的 Pull Request（#83）指出 theme.json 表单元素字段命名文档有误（应为 textInput 而非 input）并给出了修复方案。
9. 安装使用方式
- 单技能安装：
npx skills add WordPress/agent-skills --skill wp-block-themes - 批量/全局安装：克隆仓库后执行
node shared/scripts/skillpack-build.mjs --clean构建分发包，再执行node shared/scripts/skillpack-install.mjs --global（写入~/.claude/skills/等目录）或指定--dest=安装进具体项目 - 手动安装：直接复制
skills/wp-block-themes/目录到对应 AI 助手的技能目录 - 安装后注意：无需重启，AI 助手下次读取项目/全局技能目录时即可发现该技能；建议同时安装同仓库的
wp-project-triage（自动项目类型检测）与wp-block-development（区块本身开发，与主题层是互补关系）两个技能
10. 注意事项
- 需要对 WordPress 7.0+/PHP 7.4.0+ 环境有基本认知；运行主题检测脚本需要本地 Node.js 环境
- 仅覆盖区块主题本身（
theme.json/模板/图案/样式变体），不含插件架构、REST API 等主题——如需这些能力需另装同仓库其他子技能 - 内容由 AI 生成后经人工审核，涉及跨版本兼容性的细节仍建议对照官方 WordPress Block Editor Handbook 做最终交叉验证
- 已知一个未合并的社区 PR（#83）指出
theme.json表单元素文档存在字段命名错误，使用时留意该细节；全局安装的相对路径问题（issue #86）已被官方标记跟进，建议安装后先验证检测脚本能否正常执行 - OpenClaw、Hermes Agent 的兼容性未经仓库官方文档专门验证