/wp-block-theme-converter

name: wp-block-theme-converter
description: Convert any HTML/CSS/JavaScript project into a production-ready WordPress Block Theme (Full Site Editing) with Interactivity API, Block Bindings, per-block CSS, and WordPress 6.5+ best practices. Use this skill whenever the user wants to convert, port, transform, migrate, or rebuild static HTML/CSS/JS into a WordPress block theme, FSE theme, or Gutenberg-compatible theme. Also triggers for scaffolding themes from scratch, generating theme.json from design tokens, creating block patterns from HTML snippets, or building WooCommerce-compatible block themes. Trigger on phrases like "convert to WordPress", "make this a WP theme", "block theme from HTML", "FSE theme", "Gutenberg theme", "WordPress theme from scratch", "port my landing page to WordPress", "WooCommerce theme from HTML", "create a block pattern", "generate theme.json", or any request involving WordPress block theme development. Also use this skill when the user invokes the slash commands /convert-to-wp-theme, /scaffold-wp-theme, /wp-pattern, /wp-theme-json, /wp-template, /wp-block, /wp-migrate, /wp-plugin-theme, /wp-variation, or /wp-classic-to-fse. Even if the user just says "WordPress theme" or "WP theme", this skill is likely relevant.
version: 2.0.0
license: MIT

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:

| Task | Success Criteria | |------|-----------------| | Convert landing page to WP theme | Theme activates without errors. Front page renders visually identical to source. All patterns editable in Site Editor. | | Generate theme.json | JSON validates against v3 schema. Color palette matches source. Typography scale matches source. | | Create a block pattern | Pattern appears in inserter under correct category. Content is editable. No inline styles. All strings translatable. | | Add WooCommerce support | Product archive/single/cart/checkout templates render. HPOS compatibility declared. WC blocks load correctly. | | Fix editor parity | Every frontend CSS rule has a matching rule in editor.css. Visual diff between editor and frontend is zero. |

Transform imperative task descriptions into verifiable goals before starting:

| Instead of... | Transform to... | |---------------|----------------| | "Make it look right" | "Front page renders visually matching source HTML. No inline styles." | | "Fix the PHP error" | "WP_DEBUG on, error reproduced, fix applied — debug.log is clean." | | "Add WooCommerce support" | "Cart, checkout, and product archive render without warnings