editing-themes - SKILL.md Agent Skill

name: editing-themes description: Guidelines for modifying existing WordPress block themes — load this before editing theme files disable-model-invocation: true

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

NEVER recreate or overwrite files the user did not ask you to change. If the user asks to "add a newsletter template", you add the new template/pattern files and update the index template to include it — nothing else.
NEVER rewrite theme.json, functions.php, or style.css unless the user's request specifically requires changes to them (e.g., adding a new color, changing fonts, registering a new asset).
NEVER change the theme's topic, branding, or content direction. If the theme is for a dance studio, new additions must be contextually appropriate for a dance studio — not generic placeholder content.
NEVER delete existing patterns, templates, or template parts unless the user explicitly asks to remove them.

Read theme.json, style.css, and functions.php before making changes — understand the current configuration, design tokens, and registered assets
Make minimal, targeted changes — only modify what the user requested
Only touch files that need to change — do not rewrite unrelated templates or patterns
Use the edit tool for targeted changes; only use write when replacing more than 50% of a file
When modifying colors, typography, or spacing, update theme.json — not CSS — unless the change cannot be expressed in theme.json
When adding or modifying template parts, ensure they are registered in theme.json if needed
Preserve the theme's existing design direction and aesthetic unless the user explicitly asks to change it
New content (patterns, templates) must match the theme's existing topic, tone, and visual style
After changes, verify templates still reference valid template parts and patterns

Before editing theme files, read the relevant references from the creating-themes/references/ directory.

creating-themes/references/block-html.md — REQUIRED: read this FIRST. Block HTML validity rules, block comment ↔ HTML matching, image/cover/button block structure. Violating these causes "unexpected or invalid content" errors.
creating-themes/references/design-direction.md — REQUIRED: read this before generating any theme files. Contains guidelines and good design directions.
creating-themes/references/navigation.md — read this before generating any header template part, covers wp:navigation block markup, overlay (hamburger menu)
creating-themes/references/query-loop.md — read this if the theme must display dynamic content (blog posts, archives, search results) in templates or patterns