wp-block-development – WordPress 区块开发 Skill

Skill 详细介绍

automattic/agent-skills#wp-block-development 是 Automattic 官方 agent-skills 仓库中面向 WordPress 区块（Block）开发的一个 Agent Skill。它不是一个可以独立运行的软件或插件，本质是一套写给 AI Agent 的开发指导资料——包含区块开发规范、最佳实践、常见模式与检查要点，用来让 AI Agent 在处理 WordPress 区块相关任务时更专业、更少犯低级错误。

它不是什么

• 不是 WordPress 插件，不能单独安装到 WordPress 站点
• 不是 Gutenberg 编辑器本身的替代品
• 不是主题或区块模板库

核心用途

安装后，AI Agent 会在处理 WordPress 区块开发任务时获得更明确的指导，主要覆盖：

• 使用 block.json 定义区块元数据
• 区块注册（register_block_type / registerBlockType）相关写法
• edit / save 函数结构与属性（attributes）设计
• 区块的静态渲染与动态渲染（render_callback / PHP 渲染）
• 区块样式（style、editor style）与前端资源加载
• 区块的废弃（deprecated）与版本迁移
• 区块目录结构与构建工具链（如 @wordpress/scripts）

典型任务

• 从零生成一个自定义 Gutenberg 区块骨架
• 把已有短代码或旧式小工具改造为区块
• 为区块增加自定义属性、Inspector 控件、工具栏按钮
• 排查区块在编辑器中报错、验证失败、前端不渲染等问题
• 对已有区块代码按 WordPress 官方规范做代码审查

工作方式

这个 Skill 属于知识 + 规范型 Skill：它不直接执行命令，而是把 WordPress 区块开发的经验、约束与检查清单注入到 Agent 的上下文里。Agent 在实际编写代码时，会参照这些规范生成更符合 WordPress 官方推荐做法的结果。真正写文件、跑构建、装依赖这些动作仍由 Agent 的通用能力（或用户手动）完成。

适合哪些用户

• 正在开发 WordPress 主题或插件的开发者
• 需要把站点功能改造成区块化的运维/技术负责人
• 已经用 AI Agent 写代码，但希望产出更贴近 WordPress 官方规范的人

不太适合的需求

• 只想做一个纯前端静态站点（不涉及 WordPress 区块）
• 需要 WordPress 建站、主题选购、SEO 插件配置等非区块开发任务
• 需要直接操作数据库或管理 WordPress 后台的运维类任务

Skill 安全评估

从来源看，这个 Skill 来自 Automattic 官方仓库，属于可信来源。但来源可信不等于运行时无风险——实际风险取决于你的 Agent 拿到它之后做了什么。

一、这个 Skill 本身的风险

它本质是文档、规范与指令集合。不包含可执行的远程脚本、不需要 API Key、不主动联网上传数据、不要求账号或 Token。就 Skill 材质而言，风险较低。

二、真正需要关注的风险来自 Agent 行为

• 文件写入：区块开发会创建和修改主题/插件目录下的 PHP、JS、JSON、CSS 文件。如果 Agent 作用目录选错，可能覆盖无关文件。
• Shell 权限：构建区块通常需要跑 npm install、npm run build 之类的命令。若 Agent 拥有自动执行 Shell 的权限，它会真的在你机器上装依赖、跑脚本。
• 依赖供应链：@wordpress/scripts 等 npm 依赖会拉取大量第三方包，风险与直接在项目里 npm install 相同，不因用了这个 Skill 而额外增加或减少。
• 代码修改范围：Skill 会引导 Agent 按规范改代码，可能涉及重构已有区块。是否影响现有站点，取决于你怎么界定改动范围。

三、实操降低风险的建议

• 在独立分支或本地 WordPress 测试环境里开发，不要直接对生产站点动手
• 如果只需要 Skill 帮忙生成代码，可以临时关闭 Agent 的自动执行 Shell 权限，让命令由你手动执行
• 开始前明确告诉 Agent 作用目录，例如只修改 wp-content/plugins/my-block 下的文件
• 依赖安装完成后检查 package.json 与 package-lock.json，确认没有意外的包
• 改动提交前用 Git 查看 diff，逐处确认

四、边界说明

官方没有公开针对这个 Skill 的独立安全审计报告。它不涉及敏感凭证操作、不访问外网 API、不需要 OAuth，因此不存在密钥泄露类风险——但要按普通 WordPress 开发项目对待：涉及数据库、用户内容、线上部署时，仍要遵循 WordPress 自身的安全实践（如权限校验、nonce、转义输出等），Skill 不会替你保证这些。

Skill 使用要求

一、Agent / 客户端

该 Skill 属于 Automattic agent-skills 仓库，天然适配 Claude Code，在 Claude Code 中使用体验最顺畅。其他支持 Skills 或类似自定义指令加载机制的主流 Agent，也可以尝试使用，例如 Codex、Cursor、Trae、OpenClaw、WorkBuddy。官方未提供完整的第三方 Agent 兼容列表，不同 Agent 的 Skill 加载方式和触发机制差异较大，实际能否顺利挂载以对应 Agent 当前版本为准。

二、运行环境 / 依赖

Skill 本身只是资料，是否要装额外环境取决于你让它做什么。真正涉及区块开发时，本地通常需要：

三、权限

• 文件读取：必需（读取现有区块/主题代码）
• 文件写入：视任务而定，生成或修改代码时需要
• Shell：可选。构建、安装依赖时需要；只让 Agent 写代码、自己手动跑命令则可以关掉
• 网络：只在安装 npm 依赖时需要
• GitHub / 浏览器 / Docker：无必需项

四、账号 / API Key

Skill 本身不需要任何账号、API Key 或 Token。WordPress 区块开发是本地代码工作，也不需要 WordPress.com 或 Jetpack 账号。后续项目若用到第三方服务（如地图、AI 接口），才需要各自的凭证，这属于项目层面，与 Skill 无关。

最小使用条件

• 一个支持 Skill 加载的 Agent（优先 Claude Code）
• 一份可编辑的 WordPress 主题或插件目录
• 涉及构建时，本机有 Node.js / npm

Skill 安装、使用与卸载教程

一、安装

直接复制本页面提供的 Skill 安装指令，粘贴到对应的 Agent 或终端执行即可。

如果你不确定自己的 Agent 怎么装，可以直接问当前 Agent：

如何安装 automattic/agent-skills#wp-block-development？

如何在 Claude Code 中安装 automattic/agent-skills#wp-block-development？

如何在 Cursor 中安装 automattic/agent-skills#wp-block-development？

让 Agent 根据它自己的 Skill 加载 / 管理机制给出安装步骤，通常比照搬通用教程更可靠。目前没有需要额外注意的特殊官方安装条件。

二、安装后如何使用

安装完成后一般无需手动启动，当你的任务涉及 WordPress 区块开发时，Agent 会参考这个 Skill 的规范来响应。合适交给它的任务包括：新建区块、改造旧短代码、加属性与 Inspector 控件、排查区块报错、按规范审查区块代码。

使用时把需求描述清楚，最好说明：目标站点/项目路径、区块名、用途、基于哪套工具链（如 @wordpress/scripts）。示例：

使用 wp-block-development，在 wp-content/plugins/my-blocks 下新建一个名为 recipe-card 的动态区块，包含标题、图片和步骤列表三个属性。

使用 wp-block-development，帮我检查这个自定义区块的 block.json 和 register_block_type 写法是否符合 WordPress 官方推荐。

使用 wp-block-development，把这个旧的 shortcode 改造成 Gutenberg 区块，保留原有的前端输出效果。

三、卸载

卸载方式取决于你用的 Agent。多数情况下可以直接：

• 使用对应 Agent 或 Skill 管理器提供的删除功能，移除该 Skill
• 或直接问当前 Agent：如何卸载 automattic/agent-skills#wp-block-development？

不同 Agent 的 Skill 安装位置与管理方式不一样，如果没有统一卸载命令，交给当前 Agent 处理更稳妥。移除 Skill 不会影响你已经生成的代码文件。

常见问题

安装后 Agent 没识别到 Skill，怎么办？

先确认 Skill 是否真的装到了该 Agent 会扫描的目录；其次确认当前会话是否需要重启或重新加载 Skill 列表。不同 Agent 的加载时机不同，部分需要新开对话才生效。最直接的办法是问当前 Agent：你现在能用 automattic/agent-skills#wp-block-development 吗？

可以同时安装到多个 Agent 吗？

可以。Skill 文件本身不带运行时独占限制，分别在你的 Claude Code、Cursor 等环境中安装即可。但要注意不同 Agent 的加载机制不同，行为可能不完全一致。

Skill 更新后需要重新安装吗？

取决于你用哪种方式安装的。如果是从仓库自动同步，拉取到新版本即可生效；如果是手动复制，则需要重新复制最新版本覆盖。以安装时使用的机制为准。

安装这个 Skill 会改动我已有的项目吗？

不会。安装 Skill 本身只影响 Agent 的知识/上下文，不动你的项目文件。真正改文件是后续你把任务交给 Agent 时才发生。建议在 Git 分支或测试环境里操作，改动可控可回退。

可以关闭 Shell 权限只用这个 Skill 吗？

可以。如果你只让 Agent 生成或审查区块代码，不需要它跑构建，完全可以关闭自动执行 Shell 的权限。生成的代码由你手动执行 npm install、npm run build 等命令即可，安全性和可控性更高。

中国大陆使用是否需要额外网络配置？

Skill 本身不需要联网。但区块开发涉及的 npm 依赖安装在中国大陆网络下可能较慢，通常需要配置 npm 镜像源。这一步与是否使用本 Skill 无关，属于常规开发环境问题。

这个 Skill 和 WordPress 官方开发文档有什么区别？

WordPress 官方文档是给人读的参考手册；这个 Skill 是把区块开发的关键规范与检查点整理给 AI Agent 使用，让 Agent 生成的代码更贴近官方推荐做法。两者内容方向一致，但服务对象和载体不同。