How to Build a WordPress Theme with an AI Coding Agent

Can an AI coding agent actually build a WordPress theme?

Yes, an AI coding agent can build a WordPress theme, the whole thing: templates, block patterns, a design system in theme.json, custom PHP functions. I know because I did it with Claude Code, and the resulting theme ran my site from March to May 2026. Pagespeed scored 99-100.

That answer skips the part that actually matters, though: how you get there. Doing this well depends less on the tool and more on how you set the project up before you type a single prompt. Skip that step and the agent still produces something, just rarely what you actually wanted.

Here's what I learned building a full block theme with an AI coding agent, including the first attempt, which failed.

Structure before you prompt

Before you write a single line of theme code, decide your folder structure and what goes into the agent's instructions file (CLAUDE.md for Claude Code, or the equivalent for whatever you use).

A theme.json-driven block theme needs a lot of files cooperating: templates, patterns, the design token file, functions.php for custom logic, CSS on top. If the agent doesn't know how those pieces relate before it starts, it invents its own structure, and that structure rarely survives contact with the second file.

I keep a planning folder next to the theme, not inside it, so the agent's own plans and notes are still around after the code ships. You'll want to reread them later, when you've forgotten why a decision was made.

Keep the instructions file short, too. A CLAUDE.md under 40 lines that points at focused sub-documents works better than one file trying to hold every naming convention and design decision at once. The agent reads that file before every task, so bloat it and you're paying tokens for context that doesn't matter to the task at hand. If you want the deeper mechanics of why an oversized instructions file backfires, I covered it in Context Engineering: challenges and tips.

Design system first: theme.json and tokens

Before the agent touches a single template, get the design system into theme.json, the file that holds a block theme's colors, type sizes, spacing, and shadows in one place. Route every value through it, and changing one token cascades everywhere it's used, instead of you chasing the same value across a dozen files later.

Give the agent a design direction before it touches theme.json: a few reference images, some adjectives, whatever gets the point across. Mine was "retro 70s, dark surfaces, accent colors," plus screenshots I'd uploaded, no mockup, no existing site to copy. The agent still needs a starting point, because token values it invents on its own tend to land generic.

Check the result in the browser after each token change, not after the whole system is built. Small steps you can actually verify. That habit carries into every section that follows.

Templates and patterns, one at a time

Once the tokens are locked in, build one template at a time: home, blog index, single post, and whatever content types are specific to your site. Block themes structure this as templates and reusable patterns, and treating them that way in your prompts, one at a time, keeps every step small enough to actually review.

I never asked for a full page in one prompt, not once across three weeks of building. Instead: one block, checked in the browser, then the next. When two templates don't depend on each other, a capable agent runs both at once, several small tasks in parallel instead of one big one. The same small-steps discipline is behind the prompting basics I use for any agentic task, not just WordPress.

Let the agent write the Gutenberg block syntax

Gutenberg block markup has its own syntax: wp:group blocks, spacing presets, nested block comments that have to match exactly or the editor throws an error. You don't need to learn any of it first.

I didn't. I described what I wanted to see on the page, and Claude Code knew the spec and wrote block markup that matched it. What I had to bring was clarity about the outcome.

The tradeoff is that you're reviewing output instead of writing syntax, so the review has to be sharper. Check the block in the editor and on the front end both, because a block that looks right in one place can still misbehave in the other.

Where it breaks

The mistake is starting to prompt before you've settled the basics: how the project is organized, and how much the instructions file is trying to hold. Without that groundwork, the agent hands you a pile of unrelated files.

I know because it happened to me. My first attempt failed for exactly that reason. I'd copied a structure from a YouTube video, dropped a 400-line instructions file into the repo, and started typing with no design direction beyond "make it look good." The agent kept producing pieces that never agreed with each other: wrong colors, mismatched spacing, inconsistent naming.

The fix was fewer, better instructions: a file under 40 lines, paired with a folder structure decided before any code got written. The same agent, on the same task, then worked consistently across sessions.

Skipping structure cost me the whole first attempt, while doing it properly the second time round took an afternoon. If skills, the layer that stops an agent from repeating the same mistake across sessions, are new to you, my field report on Claude Code Skills covers what changed once I started using them.

Proof: what I actually built this way

I built the version above with Claude Code on top of WordPress, PHP, Gutenberg, and theme.json, working alone for about three weeks on the second, structured attempt.

It shipped with a design system routed through theme.json, templates and patterns for every content type on the site (home, blog, single posts, a photography gallery, a glossary with alphabetic navigation, tool pages, use cases), seven interactive tools built into the theme, and custom post types with structured data and sitemap controls handled through functions.php.

The theme ran eric-hinzpeter.de from March to May 2026, independent of Elementor, with a Pagespeed score of 99-100. It's since been replaced by the Next.js site you're reading now, also built with Claude Code, for reasons that had nothing to do with the theme's performance.

If you're setting up Claude Code for the first time, my getting-started guide covers installation and the CLAUDE.md problem in more depth than I could fit here.