WordPress Block Theme Converter

Convert HTML/CSS/JavaScript projects into production-ready WordPress Block Themes with Full Site Editing (FSE) support, theme.json schema v3, block patterns, templates, and WooCommerce compatibility.

Behavioral Principles

These four principles govern every decision made during theme generation. They are non-negotiable and override any temptation to "just get it done."

Tradeoff: These principles bias toward caution over speed. For trivial requests (a single-block edit, a one-line CSS fix), use judgment — not every task needs the full rigor.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before generating ANY file:

• State assumptions explicitly. If the user didn't specify a color palette, font stack, or layout strategy — say so. Don't silently invent design decisions.
• If multiple interpretations exist, present them. "Your hero section could be a core/cover block (parallax-capable) or a core/group with background image (simpler). Which do you prefer?"
• Push back when warranted. If the user asks for something that will create a poor theme (e.g., inline JS in patterns, Alpine.js for a simple toggle), say so and suggest the WordPress-native alternative.
• If something is unclear, stop. Name what's confusing. Ask. Don't generate 50 files based on a guess.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked. If the user wants a landing page theme, don't scaffold WooCommerce support, dark mode, or a newsletter pattern "just in case."
• No abstractions for single-use code. Don't create a ThemeHelper class for one function. Don't create a config.php that's only read once.
• No "flexibility" that wasn't requested. Don't add theme options panels, customizer settings, or extra block variations the user didn't ask for.
• If 200 lines could be 50, rewrite it. Every line must earn its place.
• Prefer core blocks over custom patterns. A core/media-text block is better than a custom media+text pattern that reimplements the same thing.
• Prefer theme.json over CSS. If a style can be expressed in theme.json, it MUST be. Don't write CSS for what theme.json handles natively.

The test: Would a senior WordPress theme reviewer say this is overcomplicated? If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When the user has an EXISTING theme and wants modifications:

• Don't "improve" adjacent code. If asked to add a footer pattern, don't refactor the header pattern.
• Don't refactor things that aren't broken. If the existing theme uses wp_enqueue_script() for something, don't migrate it to Interactivity API unless asked.
• Match existing style. If the theme uses tabs for indentation, use tabs. If it uses snake_case for function names, follow suit.
• If you notice unrelated issues, mention them — don't fix them. "I noticed your header pattern has an inline style attribute. Want me to fix that too?"

When YOUR changes create orphans:

• Remove imports/variables/functions that YOUR changes made unused.
• Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

For every task, define verifiable success criteria BEFORE writing code:

Transform imperative task descriptions into verifiable goals before starting:

For multi-step tasks, state a brief plan with verification at each step:

1. Audit source HTML → verify: component map produced, no ambiguity remaining
2. Generate theme.json → verify: JSON validates, all design tokens mapped
3. Create templates → verify: all pages have corresponding FSE templates
4. Register patterns → verify: patterns appear in inserter, content is editable
5. Enqueue assets → verify: no console errors, styles load correctly
6. Accessibility pass → verify: skip-link works, contrast ratios pass, ARIA attributes present

Strong success criteria let you work independently. Weak criteria ("make it look good") require constant clarification.

When to Use This Skill

Trigger this skill when the user wants to:

• Convert static HTML/CSS/JS into a WordPress theme
• Build a Full Site Editing (FSE) theme from scratch
• Scaffold theme.json, block patterns, or block templates
• Port an existing landing page, portfolio, or eCommerce site to WordPress
• Create a WooCommerce-compatible block theme
• Generate individual block patterns or templates from HTML snippets

Custom Slash Commands

When the user types one of these commands, read the corresponding command file in commands/ and execute the workflow defined there.

Core Workflow

For ANY conversion request (whether triggered by slash command or natural la