html-to-block-theme

Build a WordPress block theme from a set of static HTML designs

End-to-end conversion of a directory of static Claude Design files (HTML + linked CSS + JS + assets) into a standards-driven WordPress block theme on a local Studio site. The output reproduces the designs as closely as possible using WordPress primitives — theme.json, templates, template parts, block patterns, block styles, and page content — not hand-written CSS.

Work in phases and do not skip the blueprint. Plan the whole mapping first, get it on disk, then build section by section and refine each section against the original in a real browser. The reference guides under ${CLAUDE_PLUGIN_ROOT}/skills/html-to-block-theme/references/ are the source of truth for every mapping, standards, and tooling decision — load the relevant one before acting in each phase.

Inputs

• Design directory (required) — absolute path to a folder of static .html files plus their linked .css, .js, image, and font assets. The user provides this.
• Studio site (optional but preferred) — path or registered name of the target Studio site. If the user provides a path, use it as-is. If they don't, infer it from studio site list --format=json (match a sensible name, or ask if ambiguous). The site has a minimal block-theme scaffold the agent fully controls.

Critical environment quirks

These will silently corrupt output if missed (inherited from the Studio environment — same constraints the wpbakery-to-gutenberg skill documents):

1. Use studio wp ... --path=<site>, never bare wp. Studio sites use SQLite; the Studio-managed wp wrapper handles that connection. Bare wp from the host shell connects to nothing useful.
2. Studio's wp runs in a sandbox that cannot see the host /tmp/. Any file PHP must read inside studio wp eval-file must live inside the site directory. This skill stages such files at <site-path>/.h2bt/ and cleans them up.
3. studio wp eval-file - (stdin heredoc) can silently no-op — exit 0, no output, database unchanged. Always pass a real file path and have the PHP echo a sentinel line the caller greps for. Trust nothing without the sentinel.
4. Build files serially — all of them, not just page-content writes. Concurrent wp_update_post/wp_insert_post under SQLite trips Yoast indexable errors and corrupts results, and every builder also mutates shared theme files (functions.php, theme.json, block CSS) and refines against the same live site — a parallel builder would screenshot another's half-applied changes. So template-only files are serial too. One section-builder at a time — and "no file writes for a while" is not a completion signal (builders go quiet for long stretches during browser refinement); wait for the agent's completion notification before dispatching the next.