Wp Block Development
Ship or fix Gutenberg blocks in a WordPress plugin or theme with correct block.json, rendering, and build tooling.
Overview
WP Block Development is an agent skill for the Build phase that guides Gutenberg block.json setup, registration, dynamic rendering, deprecations, and @wordpress/scripts build workflows on WordPress 6.9+.
Install
npx skills add https://github.com/wordpress/agent-skills --skill wp-block-developmentWhat is this skill?
- Covers block.json metadata, attributes serialization, supports, and register_block_type_from_metadata workflows
- Fixes invalid blocks, saving failures, and attributes that do not persist in the editor
- Adds dynamic rendering via render.php or render_callback and handles deprecations/migrations
- Documents viewScript vs viewScriptModule and WordPress 6.9+ module constraints
- Ships deterministic triage: detect_wp_project.mjs and list_blocks.mjs to locate every block root
- Targets WordPress 6.9+ with bundled detect_wp_project and list_blocks Node scripts
- Procedure covers block.json, dynamic rendering, deprecations, and viewScriptModule
Adoption & trust: 2k installs on skills.sh; 1.6k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your WordPress block fails validation, loses attributes on save, or you need a new dynamic block without guessing block.json and build tooling.
Who is it for?
Indie developers shipping block-based themes or plugins who already have a repo and need precise Gutenberg API and tooling guidance.
Skip if: Teams only tweaking classic PHP templates with no blocks, or sites not targeting the block editor / WordPress 6.x toolchain.
When should I use this skill?
Creating or updating Gutenberg blocks, changing block.json, fixing invalid or non-persisting attributes, adding dynamic rendering, or working with @wordpress/scripts / create-block / wp-env.
What do I get? / Deliverables
You get a located block root, corrected metadata and rendering paths, and a repeatable Node-based build and test loop for that block.
- Updated block.json and registration aligned with metadata
- Dynamic render.php or render_callback implementation
- Working block build via @wordpress/scripts or create-block
Recommended Skills
Journey fit
Custom blocks are product UI and editor experience work that happens while you are building the site or plugin, not during launch SEO or ops monitoring. Gutenberg blocks are React-based frontend/editor surfaces wired through block.json and @wordpress/scripts, which maps cleanly to the frontend build shelf.
How it compares
Procedural block-editor skill for block.json and PHP render paths—not a generic React component generator or a headless CMS integration pack.
Common Questions / FAQ
Who is wp-block-development for?
Solo builders and indie teams authoring or repairing Gutenberg blocks inside WordPress plugins, themes, or full-site projects with Node and optional WP-CLI available.
When should I use wp-block-development?
Use it during Build when you create or update blocks, change block.json scripts/styles/supports, add render.php, fix invalid or non-saving blocks, or tune @wordpress/scripts and wp-env workflows.
Is wp-block-development safe to install?
Review the Security Audits panel on this Prism page and inspect the bundled Node triage scripts before running them in your production or client repo.
SKILL.md
READMESKILL.md - Wp Block Development
# 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. **Why this matters:** - WordPress 7.0 will run the post editor in an iframe regardless of block apiVersion. - apiVersion 3 ensures your block works correctly inside the iframed editor (style isolation, viewport units, media queries). **Migration:** Changing from version 2 to 3 is usually as simple as updating the `apiVersion` field in `block.json`. However: - Test in a local environment with the iframe editor enabled. - Ensure any style handles are included in `block.json` (styles missing from the iframe won't apply). - Third-party scripts attached to a specific `window` may have scoping issues. Read: - `references/block-json.md` (apiVersion and schema details) ### 3) Pick the right block model - **Static block** (markup saved into post content): implement `save()`; keep attributes serialization stable. - **Dynamic block** (server-rendered): use `render` in `block.json` (or `render_callback` in PHP) and keep `save()` minimal or `null`. - **Interactive frontend behavior**: - Prefer `viewScriptModule` for modern module-based view scripts where supported. - If you're working primarily on `data-wp-*` directives or stores, also use `wp-interactivity-api`. ### 4) Update `block.json` safely Make changes in the block’s `block.json`, then confirm registration matches metadata. For field-by-field guidance, read: - `references/block-json.md` Common pitfalls: - changing `name` breaks compatibility (treat it as stable API) - changing saved markup without adding `deprecated` causes “Invalid block” - adding attributes without defining source/serialization correctly causes “attribute not saving” ### 5) Register the bl