@automattic/creating-blocks

---

name: creating-blocks description: Templates and guidelines for creating new WordPress blocks from scratch — load this before generating block files disable-model-invocation: true

When to use me

Use this skill when creating a new block from scratch. Do not use this skill when modifying an existing block.

Generating Blocks Instructions

• Always use the current folder to generate the block
• Always remove space before the PHP opening tag, nor leave more than one empty new line at the end of any file
• Always use block props to make sure the block is selectable in the canvas
• Always use the lowercase for block name slugs
• Never close the last PHP opening tag, you always leave it open
• Never suggest or generate code outside the specification, such as REST controllers, PHP classes, or other code that is not part of a standard WordPress block
• Prefer building blocks that have the same behaviour on the frontend and the backend, unless the user asks for a block that is specifically different on the frontend
• Do not opt for placeholders in the editor
• Be proactive in adding inspector or block toolbar controls that can make the block more interactive and customizable
• Never redeclare functions in PHP and always guard with function_exists
• Do not create additional markdown files with extense documentations or installation instructions
• Make sure the block is registered correctly so that it renders on the front end
• Use the InnerBlocks component from @wordpress/block-editor as much as possible.

Interactive Blocks

When the block requires frontend interactivity (clicks, toggles, accordions, modals, carousels, counters, tabs, search filters):

• The block MUST also be dynamic (uses render.php, no save.js)
• Use plain JavaScript with standard DOM APIs (querySelector, addEventListener, classList, etc.) in view.js — never use the WordPress Interactivity API
• In block.json: use "viewScript": "file:./view.js" (not viewScriptModule)
• In render.php: use standard HTML attributes and CSS classes that your JavaScript targets
• Use data-* attributes on the block wrapper to pass server-side values to JavaScript

Reference Files

Before generating block files, read the relevant references from the references/ directory next to this skill file.

• references/artefact-templates.md — REQUIRED: read this FIRST before generating any block files. Contains exact file templates with correct paths, asset references, and build pipeline details. You MUST follow these templates exactly.
• references/file-templates.md — additional guidelines for each block file type
• references/inner-blocks.md — read this if the block uses InnerBlocks or child blocks
• references/dynamic-vs-static.md — read this if you need to decide between a dynamic, static, or interactive rendering approach
• references/interactivity-api.md — read this when creating an interactive block that needs frontend JavaScript