Build and Maintain WordPress Blocks — WordPress Gutenberg 区块开发技能

技能简介

automattic/wp-block-development 是由 Automattic 官方维护的 WordPress Gutenberg 区块开发技能，专为 Claude、Codex、Claude Code 等 AI 编程代理打造。它覆盖区块的脚手架搭建、元数据更新、序列化迁移、PHP 注册、编辑器与前端行为校验等完整生命周期，特别针对"Invalid Block"警告、apiVersion 升级失败、静态 / 动态 / 交互式区块模型选型等高频痛点提供可落地的修复流程。无论是新建区块还是为 WordPress 6.9+ 升级既有代码，该技能都能显著降低出错概率。

核心能力

• 通过只读 Node.js 扫描器定位 block.json 与相关元数据文件，安全识别目标区块。
• 引导 block.json 元数据升级，特别是 apiVersion 字段的迁移与兼容。
• 解释静态（static）、动态（dynamic）、交互式（interactive）三类区块模型差异与选型依据。
• 支持属性序列化策略与 deprecated 版本迁移，避免保存内容失效。
• 引导 PHP 端 metadata 注册、wrapper 属性与服务器端渲染逻辑。
• 提供调试、构建、Lint、测试、编辑器与前端验证的完整 checklist。

安装配置

1. 通过 npx 命令一键安装：npx skillstore add automattic/wp-block-development。
2. 启用后，AI 助手在处理 WordPress 区块项目时即可自动调用。
3. 项目需满足 WordPress ≥6.9、PHP ≥7.2.24、Node.js ≥18，并启用 Gutenberg 插件或新版 WP 内核区块编辑器。
4. 可选：安装 wp-env、wp-cli、Playwright 用于端到端验证。

使用步骤

1. 定位区块文件：调用只读扫描器定位目标区块路径，确认 block.json 与源代码位置。
2. 解读元数据：分析 apiVersion、name、attributes、supports 字段，识别过期版本与潜在风险。
3. 选择区块模型：根据内容动态性、是否需要服务端渲染、是否需要交互态，决定静态 / 动态 / 交互式类型。
4. 实施改造：更新 block.json、调整注册逻辑、添加 deprecated 版本以兼容旧保存内容。
5. PHP 端同步：确保 JavaScript 与 PHP 注册元数据完全一致，避免编辑器与前端行为不一致。
6. 完整验证：执行构建、Lint、单元测试、编辑器插入 / 保存 / 刷新、前端渲染端到端检查。

适用场景

• 从零搭建一个新的 WordPress Gutenberg 区块，覆盖元数据、渲染与测试。
• 修复生产环境中频繁出现的"Invalid Block"内容失效警告。
• 将旧版区块代码升级到 apiVersion 3，支持现代脚本与新功能。
• 为存量项目建立区块开发的统一规范与评审清单。
• 排查编辑器与前端渲染不一致的疑难问题。

适用人群

• 负责 WordPress 主题与插件开发的全栈工程师。
• 为企业站点构建自定义区块编辑体验的前端工程师。
• 维护大型 Gutenberg 站点、频繁升级 WordPress 内核的 DevOps。
• 区块开发新手，希望遵循 Automattic 官方实践快速入门。
• 准备内部 WordPress 培训材料的技术布道师。

工作原理

该技能通过预置的 WordPress 区块开发知识图谱，覆盖从 block.json 元数据到 PHP 注册、从静态到动态模型的完整决策树。AI 助手在生成代码时会先调用只读扫描器确认仓库结构，再依据 apiVersion 兼容性表与序列化规范给出最小改动方案。技能本身不修改文件，所有写入操作由用户显式确认；技能同时集成安全清单，避免在升级过程中丢失旧 saved markup，从而确保内容兼容性。

官方链接

• Skillstore 主页：https://skillstore.io/skills/automattic-wp-block-development
• 仓库地址：https://github.com/Automattic/agent-skills/tree/trunk/skills/wp-block-development
• Manifest 接口：https://skillstore.io/api/skills/automattic-wp-block-development/manifest