# Editing Blocks

> Guidelines for modifying existing WordPress blocks — load this before editing block files

- Skill: `automattic/editing-blocks` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add automattic/editing-blocks`
- Raw SKILL.md: https://api.skillmd.com/api/skills/automattic/editing-blocks/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Automattic (https://skillmd.com/u/automattic)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/automattic/editing-blocks

---


## When to use me

Use this skill when modifying an existing block (files already exist in the workspace).
Do not use this skill when creating a new block from scratch.

## Editing Guidelines

- Read all existing block files before making changes — understand the current architecture, attributes, and rendering approach
- Make minimal, targeted changes — only modify what the user requested
- Only touch files that need to change — do not rewrite unrelated files
- Use the `edit` tool for targeted changes; only use `write` when replacing more than 50% of a file
- Do not convert between static and dynamic blocks, or change the block name/slug, unless the user explicitly asks
- When adding or modifying attributes, update all relevant files (block.json, edit.js, and save.js or render.php)
- After changes, verify the block is still registered correctly and renders on the front end
- Use the InnerBlocks component from @wordpress/block-editor as much as possible.
- When adding interactivity to an existing block, convert it to dynamic first if it isn't already (add render.php, remove save.js, add `"render": "file:./render.php"` to block.json)
- When converting a block to interactive: add `"viewScript": "file:./view.js"` to block.json, write view.js using plain JavaScript with standard DOM APIs (querySelector, addEventListener, classList, etc.) — never use the WordPress Interactivity API

## Reference Files

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

- **`references/artefact-templates.md`** — read this to verify correct file structure, paths, and asset references (especially register_block_type path and block.json asset filenames)
- **`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/interactivity-api.md`** — read this when adding interactive behavior to a block that needs frontend JavaScript