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.