Index of every page on this site: llms.txt
All skills
automattic avatar

/wp-block-development

@48d4aa2 official
by automatticautomattic/agent-skills211 stars
37
Run it yourself

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.

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

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈86 tokens for metadata: the name and description. ≈1.5k when used: this file. ≈2.7k more on demand in 10 files.

Description uses 4.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈344 characters, or 4.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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 block (server-side preferred)

Prefer PHP registration using metadata, especially when:

  • you need dynamic rendering
  • you need translations (wp_set_script_translations)
  • you need conditional asset loading

Read and apply:

  • references/registration.md

6) Implement edit/save/render patterns

Follow wrapper attribute best practices:

  • Editor: useBlockProps()
  • Static save: useBlockProps.save()
  • Dynamic render (PHP): get_block_wrapper_attributes()

Read:

  • references/supports-and-wrappers.md
  • references/dynamic-rendering.md (if dynamic)

7) Inner blocks (block composition)

If your block is a “container” that nests other blocks, treat Inner Blocks as a first-class feature:

  • Use useInnerBlocksProps() to integrate inner blocks with wrapper props.
  • Keep migrations in mind if you change inner markup.

Read:

  • references/inner-blocks.md

8) Attributes and serialization

Before changing attributes:

  • confirm where the attribute value lives (comment delimiter vs HTML vs context)
  • avoid the deprecated meta attribute source

Read:

  • references/attributes-and-serialization.md

9) Migrations and deprecations (avoid "Invalid block")

If you change saved markup or attributes:

  1. Add a deprecated entry (newest → oldest).
  2. Provide save for old versions and an optional migrate to normalize attributes.

Read:

  • references/deprecations.md

10) Tooling and verification commands

Prefer whatever the repo already uses:

  • @wordpress/scripts (common) → run existing npm scripts
  • wp-env (common) → use for local WP + E2E

Read:

  • references/tooling-and-testing.md

Verification

  • Block appears in inserter and inserts successfully.
  • Saving + reloading does not create “Invalid block”.
  • Frontend output matches expectations (static: saved markup; dynamic: server output).
  • Assets load where expected (editor vs frontend).
  • Run the repo’s lint/build/tests that triage recommends.

Failure modes / debugging

If something fails, start here:

  • references/debugging.md (common failures + fastest checks)
  • references/attributes-and-serialization.md (attributes not saving)
  • references/deprecations.md (invalid block after change)

Escalation

If you’re uncertain about upstream behavior/version support, consult canonical docs first:

  • WordPress Developer Resources (Block Editor Handbook, Theme Handbook, Plugin Handbook)
  • Gutenberg repo docs for bleeding-edge behaviors

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning2mo4 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill is a legitimate tool for WordPress block development authored by Automattic. It provides standard workflows and utility scripts to manage and develop blocks. No security risks were identified.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer9mo

    12/12 files flagged

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

Last checked against GitHub last month.

Dormantupdated 11 months ago
Other metadata
compatibility
Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI.
  • React
  • wordpress
  • gutenberg
  • block-development
  • block-json
  • php
  • javascript
  • wp-scripts
  • dynamic-rendering
  • deprecations

README badge

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

Develops WordPress Gutenberg blocks: creates block.json metadata, handles block registration, static/dynamic rendering, attribute serialization, and deprecations. Targets WordPress 6.9+ with PHP 7.2.24+ and includes workflows for @wordpress/scripts, @wordpress/create-block, and block migrations.

Generated from the current SKILL.md.

What WordPress versions does this skill support?
WordPress 6.9+ with PHP 7.2.24+. The skill assumes apiVersion 3 in block.json, which is enforced in WordPress 6.9 and required for correct behavior in the iframed editor coming in WordPress 7.0.
Does this skill handle both static and dynamic blocks?
Yes. It covers static blocks (markup saved to post content), dynamic blocks (server-rendered via render.php or render_callback), and interactive blocks using viewScriptModule or the Interactivity API.
What happens if I change a block's saved markup without adding a deprecation?
Existing blocks in posts will show as invalid. You must add a deprecated entry with the old save pattern and an optional migrate function to normalize attributes when the schema changes.
Does this skill require WP-CLI or specific build tools?
Some workflows require WP-CLI. Build tooling depends on what the repo already uses — typically @wordpress/scripts or @wordpress/create-block — but the skill works with whatever is present.

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