- Home
- Skills
- Frontend & Web Apps
- WordPress Block Theme Playbook
Works with the AI Agents you already use
WordPress Block Theme Playbook
Make WordPress block themes behave: design tokens, templates, parts, patterns, and style variations that match between the Site Editor and the front end.
Free
WordPress Block Theme Playbook
Example session with this skill installed
I'm working on a WordPress block theme at wp-content/themes/nova-block. My theme.json color palette and font sizes don't show up in the Site Editor at all, the header template part referenced from templates/front-page.html disappears in the editor preview, and a new pattern I added in patterns/callout.php never appears in the inserter. Can you audit the theme folder, validate the JSON and pattern files, check whether a saved Site Editor customization is masking my defaults, and fix the files so the editor and the front end match? Keep every edit inside the nova-block theme root.
- Read your context and instructions
- Compiled the wordpress block theme
- Generated the UI component
Summary
Audited wp-content/themes/nova-block: theme.json now parses and drives every palette value, the header part slug resolves, and the Midnight variation appears in the Styles UI. Root cause of the "missing" colors was a saved Site Editor customization masking theme defaults, not the file edit.
| Item | Before | After |
|---|---|---|
| theme.json | trailing comma, all settings ignored | valid JSON v3, tokens load |
| Colors | 6 hard-coded hex values in templates | ink/accent/surface/muted slugs |
| parts/header.html | nested in parts/global/, undetected | sits directly in parts/, preview fixed |
| patterns/callout.php | PHP fatal blocked all pattern registration | php -l clean, shows in inserter |
| styles/midnight.json | absent from Styles UI | valid and selectable |
Next steps
- Reset saved customizations on the dev site to confirm precedence
- Add
contentSize/wideSizeundersettings.layoutbefore building page templates - Run
wp cache flush, then compare editor CSS variables with the front end
header.html
TSX · React component
Example file from a real run - the skill writes it into your workspace.
Connects securely to your tools. The creator never sees your data.
About this skill
Modern WordPress development requires coordinating static files with a dynamic database-driven editor. When theme.json settings don't reflect on the front end or templates appear broken in the Site Editor, the cause is usually a specific breakdown in file structure or style precedence. This skill provides the logic and commands to build, audit, and fix block themes from the file system up.
What it does
- Standardize theme.json by defining design tokens, layout widths, and per-block style overrides.
- Compose block templates using HTML files and block comments to define site-wide layouts.
- Manage template parts to create reusable regions like headers, footers, and sidebars.
- Register patterns via PHP files to provide curated content snippets in the block inserter.
- Implement style variations for quick-swapping global palettes and typography.
- Debug style precedence to identify why file-based changes are being masked by editor customizations.
How it works
- Identify the active theme using WP-CLI or file system inspection to ensure edits target the correct root.
- Validate syntax using
jqor Node.js to prevent malformed JSON from breaking the Site Editor. - Map the hierarchy by confirming slugs in templates match the files in the
parts/andpatterns/directories. - Compare environments by auditing the front-end CSS variables against the current Site Editor state.
Frameworks & tools
WordPress Block Editor (Gutenberg), theme.json (v2/v3), WP-CLI, and standard block theme file structures.
Why this beats prompting it yourself
Generic prompts often produce invalid block markup or ignore the complex precedence between files and the database. This skill enforces strict directory structures and validated JSON syntax required by the WordPress core engine.
Use cases
- Migrating a design system into
theme.jsonpresets and tokens. - Creating a child theme that overrides specific parent templates without duplication.
- Troubleshooting why a new site header isn't appearing on the live front end.
- Scaffolding a custom pattern library for client handoff.
Known limitations
Does not support classic PHP template hierarchy or legacy widget areas. Excludes dynamic block development and complex build tooling configurations.
Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Frontend & Web Apps.
Aimed at block themes only — classic PHP template hierarchies, dynamic blocks, and plugin-side extensions are out of scope. Live debugging of editor state assumes access to a development site; on production it falls back to static file analysis.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before buying a skill.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
2 uses
Times used to date
Free to use
No account required to browse
Trust & safety
Security scan
Security scan passed 1 month ago
- Free with an Agensi account
Permissions
File Scopes
Terminal access runs local WP-CLI, jq, and php -l checks; file access stays inside the single active theme folder being audited or edited.