WP Block Themes

When to use

Use this skill for block theme work such as:

• editing theme.json (presets, settings, styles, per-block styles)
• adding or changing templates (templates/*.html) and template parts (parts/*.html)
• adding patterns (patterns/*.php) and controlling what appears in the inserter
• adding style variations (styles/*.json)
• debugging “styles not applying” / “editor doesn’t reflect theme.json”

Inputs required

• Repo root and which theme is targeted (theme directory if multiple exist).
• Target WordPress version range (theme.json version and features vary by core version).
• Where the issue manifests: Site Editor, post editor, frontend, or all.

Procedure

0) Triage and locate block theme roots

1. Run triage:
   • node skills/wp-project-triage/scripts/detect_wp_project.mjs
2. Detect theme roots + key folders:
   • node skills/wp-block-themes/scripts/detect_block_themes.mjs

If multiple themes exist, pick one and scope all changes to that theme root.

1) Create a new block theme (if needed)

If you are creating a new block theme from scratch (or converting a classic theme):

• Prefer starting from a known-good scaffold (or exporting from a WP environment) rather than guessing file layout.
• Be explicit about the minimum supported WordPress version because theme.json schema versions differ.

Read:

• references/creating-new-block-theme.md

After creating the theme root, re-run detect_block_themes and continue below.

2) Confirm theme type and override expectations

• Block theme indicators:
  • theme.json present
  • templates/ and/or parts/ present
• Remember the style hierarchy:
  • core defaults → theme.json → child theme → user customizations
  • user customizations can make theme.json edits appear “ignored”

Read:

• references/debugging.md (style hierarchy + fastest checks)

3) Make theme.json changes safely

Decide whether you are changing: