# Editing Themes

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

- Skill: `automattic/editing-themes` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add automattic/editing-themes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/automattic/editing-themes/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-themes

---


## When to use me

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.

## Absolute Rules

- **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.

## Editing Guidelines

- 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

## Reference Files

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