skilld
All skills
wordpress avatar

/wp-block-development

@20324d2 official
by wordpresswordpress/agent-skills2.2k stars
327

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.

Ask your Agent

Use this Skill: https://skilld.dev/gh/wordpress/agent-skills/wp-block-development

This session only. Nothing lands on disk.

referencesblock-json.md

≈584 tokens on demand. Your agent reads this file only when SKILL.md points to it.

block.json (metadata) guidance

Use this file when you’re editing block.json fields or choosing between script/styles fields.

Practical rules

  • Treat name as stable API (renaming breaks existing content).
  • Prefer adding new functionality without changing saved markup; if markup must change, add a deprecated version.
  • Keep assets scoped: editor assets should not ship to frontend unless needed.

API version + schema

WordPress 6.9+ requires apiVersion 3. The block.json schema now only validates blocks with apiVersion: 3. Older versions (1 or 2) trigger console warnings when SCRIPT_DEBUG is enabled.

Why apiVersion 3 matters:

  • The post editor will be iframed if all registered blocks have apiVersion 3+.
  • WordPress 7.0 will always use the iframe editor regardless of apiVersion.
  • Benefits: style isolation (admin CSS won't affect editor content), correct viewport units (vw, vh), native media queries.

Migration checklist:

  1. Update apiVersion to 3 in block.json.
  2. Ensure all style handles are declared in block.json (styles not included won't load in the iframe).
  3. Test blocks that rely on third-party scripts (window scoping may differ).
  4. Add a $schema to improve editor tooling and validation.

References:

Modern asset fields to know

This is not a full schema; it’s a “what matters in practice” list:

  • editorScript / editorStyle: editor-only assets.
  • script / style: shared assets.
  • viewScript / viewStyle: frontend view assets.
  • viewScriptModule: module-based frontend scripts (newer WP).
  • render: points to a PHP render file for dynamic blocks (newer WP).

Helpful upstream references

Source: SKILL.md on GitHub

Third-party checks

1 warning16d5 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    The skill is a legitimate development assistant for WordPress block development. It includes instructions and a utility script to help developers manage block metadata, registration, and build workflows using official WordPress tools and documentation. No malicious patterns or security vulnerabilities were detected.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

  • Runlayer7mo

    12/12 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 20324d2. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 days ago.

Activeupdated 3 months ago

Capability

Other metadata
compatibility
Targets WordPress 7.0+ (PHP 7.4.0+). Filesystem-based agent with bash + node. Some workflows require WP-CLI.

Topics

  • React
  • wordpress
  • gutenberg
  • block-development
  • block-json
  • php
  • javascript
  • wp-scripts
  • dynamic-rendering
  • deprecations

README badge

README badge for wordpress/agent-skills/wp-block-development

What it does

Guides block development for WordPress 6.9+ using Gutenberg, covering block.json metadata, PHP registration, static vs dynamic rendering, attributes/serialization, deprecations, and @wordpress/scripts build workflows. Targets developers working with block.json, register_block_type, render.php, and the Block Editor's wrapper patterns.

Generated from the current SKILL.md.

Frequently asked

Does this skill work with WordPress versions before 6.9?
The skill targets WordPress 6.9+ (PHP 7.2.24+). Blocks with apiVersion 2 or lower will trigger console warnings on 6.9, and WordPress 7.0 will run the editor in an iframe regardless of block apiVersion, so migration to apiVersion 3 is recommended.
Can I use this skill for dynamic blocks with server-side rendering?
Yes. The skill covers dynamic rendering via render.php or render_callback in block.json, including best practices for wrapper attributes with get_block_wrapper_attributes().
Does this skill handle block deprecations and migrations?
Yes. The skill provides guidance on adding deprecated entries, writing save() functions for old versions, and using migrate() to normalize attributes when you change saved markup or attributes.
What build tools does this skill support?
The skill assumes you're using whatever build tooling the repo already has in place, typically @wordpress/scripts or @wordpress/create-block. It also covers wp-env for local WordPress development and E2E testing.
Does this skill require WP-CLI?
Some workflows require WP-CLI, but it is not always necessary. The skill uses filesystem-based agent work with bash and node as the primary approach.

Generated from the current SKILL.md. These answers refresh after source changes.