wp-block-themes

Overview of wp-block-themes skill

What wp-block-themes covers

The wp-block-themes skill helps with WordPress block theme work: theme.json, templates, template parts, patterns, style variations, and the common “why aren’t my styles showing up?” debugging path. It is most useful when you need a filesystem-aware, WordPress-specific workflow rather than a generic prompt about block themes.

Who should use it

Use the wp-block-themes skill if you are implementing or maintaining a block theme, converting a classic theme, or troubleshooting Site Editor behavior. It is a good fit for design implementation work where you need predictable output across frontend, editor, and user-customized styles.

Why it is different

This skill is decision-oriented: it tells you what to inspect first, what files matter, and how WordPress actually resolves theme settings versus user overrides. That makes it more useful than asking a model to “help with a block theme” because it reduces guesswork about scope, compatibility, and where a change should live.

How to Use wp-block-themes skill

Install and scope it correctly

Install with:
npx skills add WordPress/agent-skills --skill wp-block-themes

For wp-block-themes install and setup, scope the task to the active theme root before changing anything. If your repo contains multiple themes, identify the exact theme directory and the WordPress version you are targeting, because theme.json features and behavior vary by core version.

Give the skill the right input

The wp-block-themes usage pattern works best when you specify:

• the theme root or repo root
• the exact surface area: theme.json, templates/, parts/, patterns/, or styles/
• where the problem appears: Site Editor, post editor, frontend, or all three
• whether the issue is a new build, a conversion, or debugging

A strong prompt looks like: “Update the active block theme’s theme.json so buttons use the new brand color in the editor and frontend, but leave user overrides intact. WordPress 6.9 target. Check template parts if needed.”

Read these files first

Start with SKILL.md, then inspect:

• references/theme-json.md
• references/templates-and-parts.md
• references/patterns.md
• references/style-variations.md
• references/debugging.md
• references/creating-new-block-theme.md

Also check scripts/detect_block_themes.mjs when the repo structure is unclear. The wp-block-themes guide is strongest when you follow its detection step before editing.

Work in the right order

A practical workflow is:

1. detect the theme root
2. confirm the problem surface
3. inspect the relevant reference file
4. change the smallest file that should own the behavior
5. test against user customizations and cached editor state

That order matters because many “broken” block theme issues are actually style hierarchy or saved user-setting issues, not bad theme files.

wp-block-themes skill FAQ

Is wp-block-themes only for advanced users?

No. It is beginner-friendly if you already know which theme you are editing and can describe the target change clearly. The skill does the WordPress-specific routing, but you still need to provide the theme context and desired outcome.

When should I not use it?

Do not use wp-block-themes for generic WordPress plugin work, PHP template hierarchy debugging outside block themes, or visual design tasks that do not touch theme files. It is also not the best fit if you do not know whether the problem lives in the theme, user customizations, or the Site Editor.

How is it different from a normal prompt?

A normal prompt may suggest changes without checking the theme filesystem, compatibility range, or block theme file locations. The wp-block-themes skill is better when you need disciplined wp-block-themes usage across theme.json, templates, parts, and styles, especially for design implementation where exact file placement matters.

What usually blocks adoption?

The most common blockers are unclear theme scope, missing WordPress version targets, and confusion between theme defaults and user-selected styles. If you cannot answer those upfront, the skill can still help, but the first pass may be less precise.

How to Improve wp-block-themes skill

Give stronger design inputs

For better wp-block-themes for Design Implementation results, provide the exact design intent and the block or area affected. For example, say “set default heading spacing and button radius for all templates” instead of “make the theme look cleaner.” The first version is actionable; the second forces the model to invent requirements.

Separate defaults from overrides

A common failure mode is expecting theme.json changes to override user customizations. If the issue is actually in saved global styles or a selected style variation, say so. When improving results, mention whether you want:

• a theme default
• an editor control
• a style variation
• a one-off template change

Iterate using the smallest failing example

If the first output is close but not correct, narrow the next request to one file and one symptom. For example: “styles/blue.json is selected but not reflected after reload; explain whether this is expected and what to test.” That produces better debugging than asking for a broad redesign.

Validate against the repository conventions

The wp-block-themes skill improves when you check whether the repo uses patterns, style variations, or a minimal theme scaffold before editing. If your first result feels generic, re-run with the repo file path, the active theme name, and the specific reference file you want applied.