What is the wp-theme-development skill?
The wp-theme-development skill is a SKILL.md in jorgerosal/wordpress-skills for WordPress 6.6+ theme review. Your AI coding agent detects the theme type, checks theme.json, templates, template parts and block patterns, and reports findings by file with CRITICAL, WARNING and INFO severity.
The wp-theme-development skill is a WordPress theme code review workflow for WordPress 6.6+, with a primary focus on block themes and secondary coverage of classic themes for migration guidance.
Its core principle is that block themes use HTML templates with block markup and theme.json for global settings and styles. The skill treats theme.json v3 as the single source of truth for design configuration.
What the review checks
- theme.json structure and version, including the v3 defaults for font sizes and spacing sizes.
- Block template hierarchy in templates/, and classic hierarchy in PHP files.
- Template parts in parts/, registered in theme.json with a header, footer or uncategorized area.
- Global styles, style variations, block patterns in themes and child theme compatibility.
- Hardcoded styles in block templates and style.css.
How findings are reported
The skill auto-detects the theme type as block, classic, hybrid, child or WordPress.org, and adjusts guidance accordingly. Findings are grouped by file with line numbers, CRITICAL, WARNING or INFO severity labels, and BAD and GOOD code pairs.
Who the wp-theme-development skill is for
Best for
- Reviewing a block theme's theme.json, HTML templates and template parts before shipping.
- Assessing a classic theme for migration to a block theme.
- Checking WordPress.org theme submission readiness against Theme Check compliance.
Not for
- Running one evidence-led review across performance, accessibility, SEO and best practices with a re-check step, which the web-quality-audit skill covers.
- Auditing an interface against WCAG 2.2 with a severity rating, a criterion and remediation steps, which the accessibility-audit skill covers.
- Critiquing wireframes and mockups with a five-second test and severity levels, which the design-critiquer skill covers.
How to install WP Theme Development Skill: Review Block and Classic Themes
git submodule add https://github.com/jorgerosal/wordpress-skills.git .claude/plugins/wordpress-skillsgit submodule update --remote .claude/plugins/wordpress-skills. A skill copied by hand into ~/.claude/skills/ uses the unnamespaced commands.Add the repository
Run the command above in your project root. This is the recommended Option 1 for shared projects, client work and teams.
Commit the submodule
Run
git commit -m "Add WordPress Claude skills".Review a theme
Run
/wordpress-skills:wp-theme-review wp-content/themes/my-themefor a full block or classic theme review.Scan quickly
Run
/wordpress-skills:wp-theme [path]for a fast theme structure and FSE scan.
Check that it loaded
Run /wordpress-skills:wp-theme-review on a theme folder and look for findings grouped by file with CRITICAL, WARNING and INFO labels.
Key features
- Theme type detectionThe skill auto-detects block, classic, hybrid, child and WordPress.org themes. A block theme has templates/index.html and theme.json, and a classic theme has index.php and style.css.
- theme.json validationThe version field must be 3. Version 1 is flagged CRITICAL, version 2 is a WARNING with an upgrade available, and settings and styles are required sections.
- v3 default checksIn theme.json v3, defaultFontSizes and defaultSpacingSizes both default to true. A theme that defines its own sizes without setting them to false is flagged CRITICAL.
- Template hierarchy auditBlock themes require templates/index.html, with optional templates such as home.html, single.html, page.html, archive.html, 404.html and search.html. Classic themes require index.php.
- Template part checksThe parts/ directory is checked for header.html and footer.html. Registration in theme.json must match the files, with an area of header, footer or uncategorized.
- Hardcoded style detectionInline style attributes, hex color values and pixel font sizes in block themes are flagged because they defeat theme.json and block users from customizing.
- Classic-to-block migrationMost add_theme_support() calls should move to theme.json. The wp-block-styles, responsive-embeds and editor-styles supports remain acceptable in block themes.
- Severity labels with code pairsFindings carry CRITICAL, WARNING or INFO labels, are grouped by file with line numbers, and include BAD and GOOD code pairs.
- Context-aware severityHardcoded styles are a WARNING in a block theme. In a WordPress.org context, Theme Check failures are CRITICAL.
Frequently asked questions
What is the wp-theme-development skill?
It is a SKILL.md in the jorgerosal/wordpress-skills repository for WordPress theme code review and block theme development patterns on WordPress 6.6+. Your AI coding agent reviews theme.json, block templates, template parts, global styles and classic theme migration, and reports findings by file with severity labels.
How do I install the wp-theme-development skill?
Run git submodule add with the jorgerosal/wordpress-skills repository and the path .claude/plugins/wordpress-skills in your project root, then commit the change. This is the recommended project install. Afterward, run /wordpress-skills:wp-theme-review with a theme path for a full review, or /wordpress-skills:wp-theme for a fast structure scan.
Which theme types does the skill handle?
It auto-detects block, classic, hybrid, child and WordPress.org themes and adjusts its guidance. A block theme has templates/index.html and theme.json. A classic theme has index.php, style.css and functions.php. A hybrid theme has both index.php and theme.json, and a child theme has a Template header in style.css.
What does the skill check in theme.json?
It requires version 3, flags version 1 as CRITICAL and version 2 as a WARNING, and requires the settings and styles sections. It validates color, typography, spacing, layout, border and shadow settings. It also verifies the templateParts and customTemplates arrays and the useRootPaddingAwareAlignments setting.
How does the skill rank problems?
Findings carry CRITICAL, WARNING or INFO labels. Missing required files and an invalid theme.json version are CRITICAL, hardcoded values and theme.json v2 are WARNINGs, and missing style variations are INFO. Severity adjusts by context, so hardcoded styles are a WARNING in a block theme.
Does the skill review visual design?
No. The skill states that it is code review only and not UI/UX review. It examines the files that define a theme, such as theme.json, HTML templates, template parts and style variations, and flags hardcoded styles that defeat theme.json so users can customize the theme.
Does the repository also work with Codex?
The repository also ships Codex skill wrappers. To install them all, create ~/.codex/skills, copy codex-skills/* into it, and copy the claude-skills folder to ~/.codex/claude-skills. The Codex wrappers reuse the domain references stored under claude-skills, so the review heuristics stay aligned between the two agents.