Redesigning my WordPress theme with Claude skills, and deploying it through MCP

8 min read

This blog runs on ASV Minimal, a small block theme I maintain myself. A couple of weeks ago I gave it a “polish” pass: an indigo accent, a violet-to-cyan gradient, white cards with soft shadows, little all-caps date chips. It looked fine. It also looked exactly like every other page an AI assistant produces when you ask for something modern.

So I redesigned it with three Claude skills, one for each stage: design, audit and testing. Version 1.0.16 went live on this site the same evening. This post covers the skills, how to install and use them, and how the theme went live through MCP without me opening WP Admin.

What a skill is

A Claude skill is a folder with a SKILL.md file in it, sometimes with scripts or data files next to it. Claude only loads it when the task matches the skill’s description, so it costs nothing the rest of the time. Most skills install with one npx skills add command.

The three skills I used

  • Frontend Design (Anthropic): makes Claude commit to a real aesthetic, and check its plan against generic defaults, before it writes any code. I used it for the design pass.
  • Web Design Guidelines (Vercel): audits UI code against Vercel’s Web Interface Guidelines, covering accessibility, focus, forms, typography and performance. I used it for the audit.
  • Webapp Testing (Anthropic): a pattern for driving a real browser with Playwright to take screenshots and run checks. I used it for mobile and desktop testing.

My theme is plain block templates, theme.json, CSS and a little PHP. No React or build step. All three of these work on that kind of code.

Installing them

npx skills add anthropics/skills --skill frontend-design
npx skills add vercel-labs/agent-skills --skill web-design-guidelines
npx skills add anthropics/skills --skill webapp-testing

Read each SKILL.md before you rely on it. They are short, and knowing what the skill tells Claude helps you write a better brief. Webapp Testing also needs Python and Playwright.

Step 0: a local copy of the site to test against

Design work on a block theme is pointless without real rendering, so the first job was a throwaway WordPress on the same version as production (7.0.8), using SQLite so there is no database server to set up:

# WordPress at the exact production version
git clone --depth 1 --branch 7.0.8 https://github.com/WordPress/WordPress.git wp

# SQLite instead of MySQL: copy the sqlite-database-integration plugin into
# wp-content/plugins and its db.copy to wp-content/db.php, then install

# link the theme in and serve it
ln -s ~/Projects/asvignesh/asv-minimal wp/wp-content/themes/asv-minimal
php -S 127.0.0.1:8088 router.php

I seeded it with my real post titles, menu, pages and footer, plus one long post with headings, code, a table, a quote and a gist, so every style had something to land on. Then I took “before” screenshots of the live theme.

Step 1: the design pass with Frontend Design

My brief was one line: a calm, editorial tech blog. The skill makes Claude work in two passes. First a short design plan (palette, type, layout, principles). Then a review of that plan against the usual AI defaults before any code is written.

The review was humbling. My 1.0.14 theme hit almost every tell the skill lists: content chopped into identical rounded cards with the same soft shadow, gradient washes as decoration, a tracked-out all-caps eyebrow, monospace date labels, meta joined with middle dots, and one word in the headline painted in a gradient. So the revised plan threw all of that out:

  • Type: Literata for headings and reading text (it was designed for long-form reading on screens), IBM Plex Sans for the interface, system monospace only inside code. Both fonts are self-hosted in the theme, so there are no Google Fonts requests.
  • Colour: a cool near-white page, slate ink for text, and one deep ink-blue accent for links and focus. No gradients.
  • Layout: the post list is a log, not a grid of cards. Date on the left, title and excerpt on the right, and a year heading wherever the year changes.
  • One bold thing: that year-grouped log on the home page. Everything else stays quiet.

The year headings were the only part that needed PHP. The Query Loop can’t group by year, so each entry carries a post-date block with the class asv-year, and a filter blanks it when the year hasn’t changed:

add_filter( 'render_block_data', function ( $block ) {
	if ( 'core/query' === ( $block['blockName'] ?? '' ) ) {
		$GLOBALS['asv_last_year'] = null; // reset for every Query Loop
	}
	return $block;
} );

add_filter( 'render_block_core/post-date', function ( $html, $block ) {
	if ( false === strpos( $block['attrs']['className'] ?? '', 'asv-year' ) ) {
		return $html;
	}
	$year = trim( wp_strip_all_tags( $html ) );
	if ( $year === ( $GLOBALS['asv_last_year'] ?? null ) ) {
		return '';
	}
	$GLOBALS['asv_last_year'] = $year;
	return $html;
}, 10, 2 );

I kept the old class names from 1.0.14, so any template I had customised in the Site Editor would still pick up the new layout instead of breaking.

Step 2: the audit with Web Design Guidelines

This skill fetches the latest version of Vercel’s Web Interface Guidelines each time it runs and checks your files against them. I ran it on the theme files and also on the rendered pages, because a block theme’s real HTML comes from WordPress core as much as from the theme. It found 15 things worth fixing, none of them visible in a screenshot:

  • The code copy button changed its text to “Copied” but never told screen readers. It now has a live region.
  • Wide code blocks couldn’t be scrolled with the keyboard. They now get tabindex="0" when they overflow.
  • Browser translation would rewrite code identifiers, so code now carries translate="no".
  • The header search and menu buttons were smaller than a 44px touch target.
  • No theme-color, no safe-area padding for notched phones, and no overscroll-behavior on the mobile menu.
  • An old bug: the hidden search field showed up as a small white blob under the search icon.

I didn’t follow every rule. The guidelines want Title Case headings and second-person copy. This is a personal blog written in sentence case and in my own voice, so I kept both.

Step 3: screenshots and checks with Webapp Testing

Webapp Testing is mostly a pattern: start the server, wait for the network to go idle, then inspect and act. I used it to screenshot every page type at 320, 390, 820 and 1440px, to check that nothing overflows sideways, and to test the features I care about most:

page.goto(base + post)
page.wait_for_load_state("networkidle")
page.locator(".asv-code__copy").first.click()
assert page.locator(".asv-code__copy").first.text_content() == "Copied"
assert page.evaluate("navigator.clipboard.readText()").startswith("Properties")

# nothing wider than the viewport, except code and tables that scroll
overflow = page.evaluate("document.documentElement.scrollWidth")
assert overflow <= viewport_width

It caught two things the design pass missed. On phones, the copy button sat on top of the first line of code. And when the search field was open, the hover style turned the search button dark blue with a dark icon on it. Both were one-line CSS fixes. Code copy buttons, reading time, gist embeds, related posts and /page/2/ pagination all kept working.

Deploying it through MCP

This site is self-hosted but connected to WordPress.com through Jetpack, so the WordPress.com MCP connector can manage it. Uploading a theme zip takes three tool calls:

  1. wpcom-theme-upload-request returns a short-lived upload grant and a ready-made curl command.
  2. That curl sends the zip to WordPress.com storage. It has to run on a machine that holds the zip and can reach public-api.wordpress.com. For me that was my Mac, through a Claude Code Remote Control session.
  3. wpcom-theme-upload with the upload reference, the zip’s SHA-256 and overwrite: true installs it over the existing theme. Because the theme was already active, the change went live straight away.

The first upload attempt was blocked, and I’m glad it was. Claude Code on my Mac treats a curl that sends a file to an outside server as possible data exfiltration. It won’t run it until I type the go-ahead myself. Approval relayed from another chat doesn’t count. That’s one extra message from me, and it’s the right default.

After the install, wpcom-rendered-page-get read the live pages as a logged-out visitor sees them: the new heading structure, the post list and the /page/2/ canonicals were all correct. That check also turned up an unrelated bug, a broken Rank Math variable in my About page’s SEO title. One limit to know about: the connector can’t write Rank Math’s own fields, so plugin settings like those still need WP Admin or hosting access.

What I took away

  • The skills do change the output. Frontend Design’s habit of naming the generic defaults before writing any code was the most valuable part, because it named the exact things that made my last version look templated.
  • Use them as a sequence: design, then audit, then test in a real browser. Each one caught things the one before it couldn’t see.
  • Test against a real WordPress on the production version, not static HTML. Half of what the audit found came from core block markup, not my templates.
  • Keep a person in the loop for the irreversible step. Everything up to the deploy happened on a local copy. Going live took my explicit “publish”, and the upload took my own go-ahead on the Mac.

Leave a Reply

Discover more from Vignesh A S

Subscribe now to keep reading and get access to the full archive.

Continue reading