# Wp Block Development

Use when developing WordPress (Gutenberg) blocks: block.json metadata...

- Repository: https://github.com/WordPress/agent-skills (2319 stars)
- Category: Testing
- License: see repository
- Last updated: 2026-10-26
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add WordPress/agent-skills --skill wp-block-development -g -a claude-code -y`
Codex: `npx skills add WordPress/agent-skills --skill wp-block-development -g -a codex -y`
Cursor: `npx skills add WordPress/agent-skills --skill wp-block-development -g -a cursor -y`
Gemini CLI: `npx skills add WordPress/agent-skills --skill wp-block-development -g -a gemini-cli -y`

## Description

Use when developing WordPress (Gutenberg) blocks: block.json metadata, register_block_type(_from_metadata), attributes/serialization, supports, dynamic rendering (render.php/render_callback), deprecations/migrations, viewScript vs viewScriptModule, and @wordpress/scripts/@wordpress/create-block build and test workflows.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# WP Block Development

## When to use

Use this skill for block work such as:

- creating a new block, or updating an existing one
- changing `block.json` (scripts/styles/supports/attributes/render/viewScriptModule)
- fixing “block invalid / not saving / attributes not persisting”
- adding dynamic rendering (`render.php` / `render_callback`)
- block deprecations and migrations (`deprecated` versions)
- build tooling for blocks (`@wordpress/scripts`, `@wordpress/create-block`, `wp-env`)

## Inputs required

- Repo root and target (plugin vs theme vs full site).
- The block name/namespace and where it lives (path to `block.json` if known).
- Target WordPress version range (especially if using modules / `viewScriptModule`).

## Procedure

### 0) Triage and locate blocks

1. Run triage:
   - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
2. List blocks (deterministic scan):
   - `node skills/wp-block-development/scripts/list_blocks.mjs`
3. Identify the block root (directory containing `block.json`) you’re changing.

If this repo is a full site (`wp-content/` present), be explicit about *which* plugin/theme contains the block.

### 1) Create a new block (if needed)

If you are creating a new block, prefer scaffolding rather than hand-rolling structure:

- Use `@wordpress/create-block` to scaffold a modern block/plugin setup.
- If you need Interactivity API from day 1, use the interactive template.

Read:
- `references/creating-new-blocks.md`

After scaffolding:

1. Re-run the block list script and confirm the new block root.
2. Continue with the remaining steps (model choice, metadata, registration, serialization).

### 2) Ensure apiVersion 3 (WordPress 6.9+)

WordPress 6.9 enforces `apiVersion: 3` in the block.json schema. Blocks with apiVersion 2 or lower trigger console warnings when `SCRIPT_DEBUG` is enabled.

The rest: https://github.com/WordPress/agent-skills/blob/HEAD/skills/wp-block-development/SKILL.md