skilld
All skills
automattic avatar

/wp-block-themes

@95e374f official
by automatticautomattic/agent-skills211 stars
37

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/automattic/agent-skills/wp-block-themes

This session only. Nothing lands on disk.

referencesdebugging.md

≈181 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).

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 warning16d4 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    The skill is safe and designed for WordPress block theme development. It includes standard documentation and a script that scans local directories to identify block themes based on the presence of theme.json and related folders. No security risks or malicious behaviors were detected.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

  • Runlayer7mo

    7/8 files flagged

Provenance

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

Last checked against GitHub 5 months ago.

Dormantupdated 9 months ago

Capability

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

Topics

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

README badge

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

What it does

Guides WordPress block theme development with theme.json editing, templates, template parts, patterns, and style variations for WordPress 6.9+. Use this when building or debugging block themes, including style hierarchy troubleshooting and Site Editor issues.

Generated from the current SKILL.md.

Frequently asked

Does this skill work with WordPress versions before 6.9?
No. The skill targets WordPress 6.9+ (PHP 7.2.24+). Block theme features and theme.json schema versions vary significantly across core releases, so earlier versions are not supported.
Can I use this skill to convert a classic theme to a block theme?
Yes. The skill includes guidance in `references/creating-new-block-theme.md` for converting classic themes, though it recommends starting from a known-good scaffold or exporting from a WP environment rather than building from scratch.
What should I do if theme.json changes don't appear in the Site Editor or frontend?
Start with `references/debugging.md`. Common causes are editing the wrong theme root, invalid theme.json syntax, user customizations overriding theme defaults, or caching. The skill covers the style hierarchy (core defaults → theme.json → child theme → user customizations) to help diagnose which layer is controlling the output.
Does this skill handle block theme assets like fonts and custom CSS builds?
The skill covers theme.json, templates, patterns, and style variations but expects you to run the repo's own build/lint scripts if custom assets (fonts, compiled CSS/JS) are involved.

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