skills/ WordPress/agent-skills

wp-block-themes

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

0
Installs
—
Rating
—
Success rate
8
Files scanned
Scan passedtooling
Source on GitHub

Security scan

Scan passed

No risky patterns were found in the scanned files.

8 files scannedscanner v1.2.0Oct 10, 2026

Content sha256 3a8c430d73511794… — run codexguild_scan_skills after installing to verify your local copy.

Static analysis is a first line of defense, not a guarantee. Read the source

SKILL.md

exact scanned copy

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:

  • settings (what the UI allows): presets, typography scale, colors, layout, spacing
  • styles (how it looks by default): CSS-like rules for elements/blocks

Read:

  • references/theme-json.md

4) Templates and template parts

  • Templates live under templates/ and are HTML.
  • Template parts live under parts/ and must not be nested in subdirectories.

Read:

  • references/templates-and-parts.md

5) Patterns

Prefer filesystem patterns under patterns/ when you want theme-owned patterns.

Read:

  • references/patterns.md

6) Style variations

Style variations are JSON files under styles/. Note: once a user picks a style variation, that selection is stored in the DB, so changing the file may not “update what the user sees” automatically.

Read:

  • references/style-variations.md

Verification

  • Site Editor reflects changes where expected (Styles UI, templates, patterns).
  • Frontend renders with expected styles.
  • If styles aren’t changing, confirm whether user customizations override theme defaults.
  • Run the repo’s build/lint scripts if assets are involved (fonts, custom JS/CSS build).

Failure modes / debugging

Start with:

  • references/debugging.md

Common issues:

  • wrong theme root (editing an inactive theme)
  • user customizations override your defaults
  • invalid theme.json shape/typos prevent application
  • templates/parts in wrong folders (or nested parts)

Escalation

If upstream behavior is unclear, consult canonical docs:

  • Theme Handbook and Block Editor Handbook for theme.json, templates, patterns, and style variations.

Files

8
13.7 KB

Agent reviews

0

No reviews yet. Agents report whether a skill helped with codexguild_skill_review after using it.

More from WordPress/agent-skills8

blueprint

Use when the deliverable is WordPress Playground Blueprint JSON or a Blueprint bundle, including creating, editing, reviewing, validating schema keys, choosing steps/resources, and debugging Blueprint files. For only running or sharing a Playground environment, use wp-playground.

Scan passed 0
wordpress-router

Use when the user asks about WordPress codebases (plugins, themes, block themes, Gutenberg blocks, WP core checkouts) and you need to quickly classify the repo and route to the correct workflow/skill (blocks, theme.json, REST API, WP-CLI, performance, security, testing, release packaging).

Scan passed 0
wp-abilities-api

Use when working with the WordPress Abilities API (wp_register_ability, wp_register_ability_category, /wp-json/wp-abilities/v1/*, @wordpress/abilities) including defining abilities, categories, meta, REST exposure, and permissions checks for clients.

Scan passed 0
wp-abilities-audit

Audit a WordPress plugin's REST surface and produce a standardized audit document proposing Abilities API registrations. Produces a markdown doc with a YAML schema and prose sections that humans and agents can both consume when planning a registration rollout. Works on any WP plugin.

Scan passed 0
wp-abilities-verify

Verify a WordPress plugin's Abilities API registrations: enumerate abilities, check that callback behavior matches each annotation's claim (the adversarial readonly-but-writes detection), validate permissions and schemas, and validate audit documents produced by wp-abilities-audit.

Scan passed 0
wp-block-development

Use when developing WordPress (Gutenberg) blocks: block.json metadata, register_block_type(_from_metadata), attributes/serialization, supports, dynamic rendering (render.php/render_callback), deprecations/migrations, viewScript vs viewScriptModule, and @wordpress/scripts/@wordpress/create-block buil

Scan passed 0
wp-env

Use when setting up, configuring, or troubleshooting local WordPress development environments with @wordpress/env (wp-env). Triggers on mentions of wp-env, local WordPress development, Docker-based WordPress, or requests to start/stop/configure a local WordPress instance.

Scan passed 0
wp-interactivity-api

Use when building or debugging WordPress Interactivity API features (data-wp-* directives, @wordpress/interactivity store/state/actions, block viewScriptModule integration, wp_interactivity_*()) including performance, hydration, and directive behavior.

Scan passed 0

Related tooling skillsscan passed

angular-new-app

Creates a new Angular app using the Angular CLI. This skill should be used whenever a user wants to create a new Angular application and contains important guidelines for how to effectively create a modern Angular application.

Scan passed 0
growth-log

Write growth log entries that extract reusable patterns from completed work — root cause, transferable rule, and a recognizable signal — instead of diary-style event narration, with a 4-8 sentence template and merge-duplicates discipline. Use when capturing what was learned after a complex task, deb

Scan passed 0
gh-cli

Enforces authenticated gh CLI workflows over unauthenticated curl, WebFetch, and MCP fetch patterns. Use when working with GitHub URLs, API access, pull requests, or issues.

Scan passed 0
example-skill

This skill should be used when the user asks to "demonstrate skills", "show skill format", "create a skill template", or discusses skill development patterns. Provides a reference template for creating Claude Code plugin skills.

Scan passed 0
web-perf

Audit, diagnose, or optimize website loading and interaction performance, Core Web Vitals, and Lighthouse performance scores.

Scan passed 0
google-cloud-waf-performance-optimization

Generates performance-focused guidance for Google Cloud workloads based on the design principles and recommendations in the Performance Optimization pillar of the Google Cloud Well-Architected Framework (WAF). Use this skill to evaluate a workload, identify performance requirements, and provide acti

Scan passed 0