# Build WordPress Block Themes

WordPress block themes require precise theme.json, template, pattern, and style variation structure. This skill gives Claude, Codex, and Claude Code targeted guidance for safe theme edits and debugging.

## Install

```bash
npx skillstore add automattic/wp-block-themes
```

## Metadata

- - Slug: automattic-wp-block-themes
- - Version: 1.0.0
- - Author: Automattic
- - GitHub username: Automattic
- - License: MIT
- - Repository: https://github.com/Automattic/agent-skills/tree/trunk/skills/wp-block-themes
- - Ref: trunk
- - Supported tools: Claude, Codex, Claude Code
- - Risk level: low
- - Risk factors: scripts, external\_commands, network, filesystem
- - Quality score: 80
- - Quality tier: silver
- - Public page: https://skillstore.pages.dev/skills/automattic-wp-block-themes
- - Manifest: https://skillstore.pages.dev/api/skills/automattic-wp-block-themes/manifest

## Capabilities

- Identifies block theme roots by locating theme.json and template or part folders.
- Guides safe edits to theme.json settings, presets, styles, and per-block rules.
- Explains template, template part, pattern, and style variation folder conventions.
- Helps debug Site Editor issues caused by user customizations or invalid theme.json shape.
- Points to WordPress handbook references for current block theme behavior.

## Use Cases

- Create a New Block Theme: Use the skill to plan the minimum file structure, choose a theme.json version, and verify block theme folders.
- Debug Style Overrides: Use the skill to check whether user customizations, child themes, or invalid theme.json data override expected styles.
- Maintain Theme Patterns: Use the skill to organize filesystem patterns, templates, parts, and style variations without breaking editor expectations.

## Prompt Templates

### Find My Block Theme

```
Use the wp-block-themes skill to inspect this repository and identify the active block theme structure.
```

### Add Theme Settings

```
Use the wp-block-themes skill to add editor-visible color and spacing presets to my theme.json.
```

### Fix Site Editor Styles

```
Use the wp-block-themes skill to explain why my Site Editor styles differ from the frontend and propose checks.
```

### Plan a Theme Conversion

```
Use the wp-block-themes skill to plan a classic theme to block theme conversion with templates, parts, patterns, and validation steps.
```

## Limitations

- Does not create a full WordPress runtime or database for testing.
- May require WP-CLI or a local WordPress site for complete verification.
- Targets WordPress 6.9 and later guidance, so older projects need compatibility checks.
- Does not replace visual review in the Site Editor and frontend.

## Best Practices

- Confirm the target theme root before editing any theme files.
- Validate theme.json structure after changing settings, styles, or block rules.
- Test changes in both the Site Editor and frontend because overrides can differ.

## Anti Patterns

- Editing an inactive theme and assuming the Site Editor will reflect the change.
- Using custom CSS before checking whether theme.json supports the required style.
- Changing a selected style variation without testing reset or fresh-user behavior.

## Security Audit

- - Safe to publish: true
- - Audited at: 2026-06-28T11:44:03.479\+00:00
- - Summary: Static analysis reported many high-risk patterns, but review found no malicious intent, no prompt injection, and no confirmed weak cryptography. Most command and crypto matches are Markdown backticks around WordPress terms, file paths, or documentation links. The only real concern is a local Node.js helper that reads the current repository to detect block theme folders.

## Stats

- - Views: 208
- - Downloads: 4
- - Favorites: 0
- - Popularity score: 0