wp-block-theme-converter

WordPress Block Theme Converter Skill

A Claude Code plugin (and standalone skill) for converting any HTML/CSS/JavaScript project into a production-ready WordPress Block Theme (Full Site Editing).

Author: Md Siddiqur Rahman Version: 2.0.0 License: MIT

---

What This Skill Does

Converts static HTML/CSS/JavaScript projects into complete, production-ready WordPress block themes that are:

• ✅ Compatible with WordPress 6.5+
• ✅ Full Site Editing (FSE) ready
• ✅ Accessible (WCAG 2.1 AA)
• ✅ Performance-optimized (Core Web Vitals)
• ✅ Translation-ready (i18n)
• ✅ WooCommerce-compatible (optional)
• ✅ WordPress.org Theme Directory submission-ready
• ✅ CI/CD pipeline ready (GitHub Actions)
• ✅ E2E tested (Playwright)

Custom Slash Commands

Command	Purpose
/convert-to-wp-theme	Full conversion of HTML/CSS/JS project to complete block theme
/scaffold-wp-theme	Create empty block theme scaffold (no source needed)
/wp-pattern	Convert single HTML section into a registered block pattern
/wp-theme-json	Generate theme.json from CSS custom properties / design tokens
/wp-template	Convert single HTML page into FSE template
/wp-block	Scaffold a custom block (block.json, edit.js, save.js/render.php, CSS)
/wp-migrate	Migrate existing WP content (Classic Editor, ACF, widgets, CPTs, shortcodes) to block theme
/wp-plugin-theme	Declare plugin dependencies and generate plugin-specific CSS / compatibility code
/wp-variation	Generate a style variation (styles/*.json) — dark mode, color palette swap, font swap
/wp-classic-to-fse	Convert an existing WordPress classic theme (PHP templates) to FSE block theme
/wp-debug	Diagnose and fix FSE/block-theme failures — block validation errors, theme.json issues, patterns not showing, DB template overrides, PHP warnings, and more

Installation

Option 1: Claude Code plugin (recommended)

This repository is also a Claude Code plugin marketplace. Install it directly from GitHub:

# Run these inside Claude Code:
/plugin marketplace add siddik-web/wp-block-theme-converter
/plugin install wp-block-theme-converter@siddik-web

Installing the plugin registers everything at once:

• All 11 slash commands (/convert-to-wp-theme, /wp-debug, …)
• The wp-block-theme-converter skill (auto-triggers on WordPress requests)
• The wp-theme-reviewer agent for auditing generated themes
• A non-blocking theme.json validation hook that runs after edits

Manage or disable it any time with /plugin.

Option 2: Claude Code skill (manual)

1. Download or clone this repository

2. Place the folder in your Claude Code skills directory:

   ~/.claude/skills/wp-block-theme-converter/
   

3. Restart Claude Code or run claude reload

4. Verify: type any of the slash commands listed above

Option 3: Claude.ai (Project Skills)

1. Open a Claude.ai Project
2. Project settings → Skills → Upload Skill
3. Upload wp-block-theme-converter.skill
4. The skill will be available in all conversations within that project

Option 4: Manual (Cowork / Other Environments)

Place the wp-block-theme-converter/ folder in your skills directory. Path varies by environment:

• Cowork: ~/skills/
• Custom: Configure via CLAUDE_SKILLS_DIR environment variable

Usage

Basic Workflow

1. Open a conversation with Claude (Code, Desktop, or Web)
2. Invoke a slash command OR describe your task in natural language
3. Provide your source HTML/CSS/JS (paste or attach files)
4. Claude generates the complete theme following the 10-phase methodology
5. Download/copy the files and install in WordPress

Example: Quick Landing Page

/convert-to-wp-theme

I have a 3-page landing site for "Acme Co".
Use Vite 6, no WooCommerce.

[paste HTML/CSS/JS]

Example: WooCommerce Theme

/convert-to-wp-theme

Convert my Northaven Co. eCommerce design system to a WooCommerce block theme.
Include all six aesthetics as style variations.

[attach HTML files]

Example: Pattern Only

/wp-pattern

Convert this hero section into a WP block pattern:

<section class="hero">
  <h1>Welcome</h1>
  <p>Subheading</p>
  <a href="#" class="btn">CTA</a>
</section>

Example: Custom Block

/wp-block

Scaffold a "Testimonial Slider" custom block with server-side rendering,
an edit.js with InspectorControls, and per-block CSS.

Example: Classic Theme Migration

/wp-classic-to-fse

Convert my existing classic PHP theme to a full FSE block theme.
The theme uses a custom page builder and ACF fields.

Plugin Structure

wp-block-theme-converter/                 # Plugin root (also a marketplace)
├── .claude-plugin/
│   ├── plugin.json                       # Plugin manifest
│   └── marketplace.json                  # Marketplace entry (installable)
│
├── SKILL.md                              # The bundled skill (auto-triggers)
├── README.md                             # This file
│
├── commands/                             # 11 slash command definitions
│   ├── convert-to-wp-theme.md
│   ├── scaffold-wp-theme.md
│   ├── wp-block.md
│   ├── wp-classic-to-fse.md
│   ├── wp-debug.md
│   ├── wp-migrate.md
│   ├── wp-pattern.md
│   ├── wp-plugin-theme.md
│   ├── wp-template.md
│   ├── wp-theme-json.md
│   └── wp-variation.md
│
├── agents/                               # Subagents
│   └── wp-theme-reviewer.md              # Audits a generated block theme
│
├── hooks/
│   └── hooks.json                        # PostToolUse theme.json validation
│
├── references/                           # Detailed reference docs
│   ├── defaults.md                       # Default values for placeholders
│   ├── methodology.md                    # 10-phase conversion methodology
│   ├── modern-blocks.md                  # WordPress 6.5+ features (Interactivity API, Block Bindings, etc.)
│   ├── file-structure.md                 # Required output directory layout
│   ├── block-conversion-map.md           # HTML → WP block lookup table
│   ├── theme-json-schema.md              # theme.json v3 reference
│   ├── quality-rules.md                  # Non-negotiable do's and don'ts
│   ├── multi-turn-strategy.md            # Splitting large projects
│   ├── woocommerce.md                    # WC-specific theming
│   ├── validation-checklist.md           # Post-generation checks
│   ├── custom-blocks.md                  # Custom block development (block.json, edit.js, render.php)
│   ├── content-migration.md              # Classic-to-block, WP-CLI, ACF, CPTs, page builder migration
│   ├── asset-optimization.md             # Fonts, images, WebP, lazy load, Core Web Vitals
│   ├── plugin-compatibility.md           # Plugin detection, CSS conflicts, caching compat
│   ├── interactivity-api-advanced.md     # Shared store, server hydration, async, focus traps
│   ├── accessibility.md                  # WCAG 2.1 AA, ARIA, skip links, screen reader testing
│   ├── ci-cd.md                          # GitHub Actions, PHPCS, ESLint, Stylelint, deployment
│   ├── backward-compatibility.md         # Feature availability by WP version, conditional loading
│   ├── e2e-testing.md                    # Playwright, visual regression, a11y scans, CI integration
│   └── i18n.md                           # i18n functions, plural forms, JS translations, RTL
│
├── templates/                            # Reusable boilerplate
│   ├── style.css.tpl
│   ├── theme.json.tpl
│   ├── functions.php.tpl
│   ├── pattern-header.php.tpl
│   ├── template-skeleton.html.tpl
│   ├── package.json.tpl
│   ├── vite.config.js.tpl
│   ├── github-actions-ci.yml.tpl
│   └── patterns/
│       ├── hero.php.tpl
│       ├── features-grid.php.tpl
│       ├── testimonials.php.tpl
│       ├── pricing-table.php.tpl
│       ├── cta-section.php.tpl
│       ├── faq-accordion.php.tpl
│       ├── team-grid.php.tpl
│       └── stats-row.php.tpl
│
├── examples/                             # Worked examples
│   ├── northaven-ecommerce.md            # Multi-aesthetic WooCommerce theme
│   └── landing-page-simple.md            # Simple SaaS landing page
│
└── scripts/                              # Validation + packaging tooling
    ├── doctor.mjs                        # Runs all four theme-quality checks
    ├── validate-skill.mjs                # Skill integrity linter
    ├── validate-plugin.mjs               # Plugin packaging linter
    └── hooks/
        └── theme-json-postwrite.mjs      # theme.json validation hook runner

How It Works

Progressive Disclosure

The skill uses Claude's three-level loading:

1. SKILL.md metadata — always in context (~100 words)
2. SKILL.md body — loaded when skill triggers (~400 lines)
3. Reference files — loaded on-demand as needed

This means Claude doesn't load the WooCommerce reference for a simple landing page conversion — it only loads what's relevant to the task.

10-Phase Methodology

Every conversion follows the same proven phases:

1. Audit & Extract — parse source, identify reusable components
2. theme.json — generate schema v3 with full settings + styles (incl. Section Styles, dimensions, position)
3. Templates & Parts — convert HTML pages to FSE block markup
4. Block Patterns — register sections as reusable patterns
5. Block Styles & Variations — register custom variants via theme.json + PHP
6. JavaScript Integration — Interactivity API for interactive patterns; classic enqueue for complex libs
7. functions.php & inc/ — bootstrap files (WP Coding Standards)
8. Accessibility & Performance — WCAG 2.1 AA + Core Web Vitals + per-block CSS + font preloading
9. i18n — translation-ready strings everywhere
10. README & Docs — WordPress.org-format readme.txt

Multi-Turn for Large Projects

The skill automatically detects large projects and splits delivery across 3 turns:

• Turn 1: Foundation (theme.json, templates, parts, functions.php)
• Turn 2: Patterns + Block Styles + Style Variations
• Turn 3: JavaScript + Assets + Docs

Triggered when source has 10+ HTML pages OR WooCommerce OR multiple style variations.

Behavioral Principles

Every output is governed by four non-negotiable principles:

1. Think Before Coding — surface assumptions, present tradeoffs, ask before guessing
2. Simplicity First — minimum code that solves the problem; no speculative features
3. Surgical Changes — touch only what the task requires; don't improve adjacent code
4. Goal-Driven Execution — define verifiable success criteria before writing any file

Quality Guarantees

Every theme generated follows these non-negotiable rules:

• ❌ NO inline <style> or <script> tags
• ❌ NO style="" attributes (use block attributes)
• ❌ NO hardcoded colors/spacing in CSS (use CSS custom properties)
• ❌ NO unescaped output
• ❌ NO direct database queries
• ❌ NO Alpine.js for interactions the Interactivity API can handle
• ❌ NO physical CSS directional properties (use logical properties for RTL)
• ❌ NO speculative features the user didn't ask for
• ✅ All strings translation-ready
• ✅ Semantic HTML via tagName
• ✅ theme.json as single source of truth
• ✅ WCAG 2.1 AA compliant
• ✅ Versioned assets for cache-busting
• ✅ Interactivity API for interactive patterns (modals, tabs, toggles)
• ✅ Per-block CSS loading via wp_enqueue_block_style()
• ✅ Font preloading for critical fonts
• ✅ Section Styles for coordinated dark/highlight sections
• ✅ Editor parity — all frontend CSS mirrored in editor.css

Production / Reliability

Automated Output Verification

Every theme generated by this skill can be verified using the bundled scripts: