wp-block-development_skill

Overview

This skill helps you develop and maintain WordPress (Gutenberg) blocks, covering block.json metadata, registration, attributes/serialization, dynamic rendering, deprecations/migrations, and build/test workflows. It packages practical checks and commands to find blocks, scaffold new blocks, and validate editor/frontend behavior across WordPress versions.

How this skill works

Run the repo triage and block scan to locate block roots and identify plugin vs theme contexts. Update or scaffold blocks, choose the correct block model (static, dynamic, interactive), edit block.json and registration code, and apply migrations/deprecations when saved markup changes. Use the provided tooling guidance to build, run local WP environments, and verify editor and frontend outputs.

When to use it

• Creating a new block or scaffolding a modern block plugin
• Changing block.json fields (apiVersion, attributes, styles, viewScriptModule)
• Fixing ‘Invalid block’, attributes not persisting, or save/load mismatches
• Adding dynamic rendering via render.php or render_callback
• Implementing deprecations and migrations for changed saved markup
• Setting up or debugging build/test workflows with @wordpress/scripts and wp-env

Best practices

• Keep apiVersion at 3 for modern editor iframe behavior and style isolation
• Prefer PHP registration from metadata when you need translations or conditional loading
• Treat block name/namespace as a stable API — avoid changing it
• When changing saved markup, add deprecated versions with save and optional migrate
• Use useBlockProps/useBlockProps.save and get_block_wrapper_attributes for consistent wrappers
• Use viewScriptModule for modern module-based front-end interactivity where supported

Example use cases

• Scaffold a new interactive block using @wordpress/create-block and confirm registration
• Migrate a block from apiVersion 2 to 3 and validate styles in the iframe editor
• Add server-side rendering for a dynamic listing block via render_callback in PHP
• Fix an attribute serialization bug by correcting attribute source and adding a migration
• Add a deprecated save implementation to avoid creating 'Invalid block' after markup changes