skilld
All skills
wordpress avatar

/wp-block-themes

@20324d2 official
by wordpresswordpress/agent-skills2.2k stars
327

Use when developing WordPress block themes: theme.json (global settings/styles), templates and template parts, patterns, style variations, and Site Editor troubleshooting (style hierarchy, overrides, caching).

Ask your Agent

Use this Skill: https://skilld.dev/gh/wordpress/agent-skills/wp-block-themes

This session only. Nothing lands on disk.

referencesdebugging.md

≈252 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Debugging block theme issues

Styles not applying

Fast checks:

  1. Confirm you edited the active theme (Site Editor → theme).
  2. Check if user customizations exist (they override theme defaults).
  3. Validate theme.json structure (typos can prevent styles from applying).
  4. If a var(--wp--preset--*) / var(--wp--custom--*) reference is silently using its fallback, the slug is likely un-normalised — WordPress hyphenates digit/letter boundaries and camelCase transitions before emitting the CSS var. See theme-json.md § "Slug normalisation gotcha".

Remember the hierarchy:

  • core defaults → theme.json → child theme → user customizations

Templates/parts not showing

  • Ensure files are in the correct folders (templates/, parts/).
  • Template parts must not be nested in subdirectories.

Style variations not updating

  • If a user already selected the variation, the selection is stored in the DB.
  • Test with a fresh site/user or reset customizations when appropriate.

Source: SKILL.md on GitHub

Third-party checks

1 warning17d5 checks · Risk SAFE
  • Gen Agent Trust Hub17d

    The skill provides comprehensive guidance and a local analysis tool for developing WordPress block themes. It operates safely within the local repository, performing file discovery and referencing official documentation.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: LOW · No issues

  • Runlayer7mo

    8/8 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 20324d2. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 days ago.

Activeupdated 3 months ago

Capability

Other metadata
compatibility
Targets WordPress 7.0+ (PHP 7.4.0+). Filesystem-based agent with bash + node. Some workflows require WP-CLI.

Topics

  • wordpress
  • block-themes
  • theme-json
  • site-editor
  • templates
  • patterns
  • php
  • bash

README badge

README badge for wordpress/agent-skills/wp-block-themes

What it does

Edits WordPress block theme files (theme.json, templates, template parts, patterns, style variations) and debugs why styles don't apply in the Site Editor or frontend. Targets WordPress 6.9+ and assumes a filesystem-based workflow with WP-CLI integration.

Generated from the current SKILL.md.

Frequently asked

What WordPress versions does this skill support?
WordPress 6.9+ with PHP 7.2.24+. The skill is version-aware because theme.json schema and features vary across WordPress core versions.
Does this skill work with classic themes?
No. This skill targets block themes only. It handles theme.json, templates, template parts, patterns, and style variations — all block theme constructs.
What happens if user customizations override my theme.json changes?
User customizations take precedence in the style hierarchy. The skill includes debugging guidance to detect and distinguish between theme defaults and stored user overrides.
Can I use this skill to create a block theme from scratch?
Yes. The skill includes a scaffold reference and recommends starting from a known-good template rather than guessing file layout.
Does this skill require WP-CLI?
Not always, but some workflows do. The skill is filesystem-based and uses bash and Node, with WP-CLI required for certain tasks.

Generated from the current SKILL.md. These answers refresh after source changes.