wp-block-themes
Use when developing WordPress block themes: theme.json (global settings/styles), templates and template parts, patterns, style variations, and Site Editor troubleshooting (style hierarchy, overrides, caching).
- Installs
- 5.9K
- Last 24h
- +44
- Trending rank
- #3647
- Security
- Warn
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/wordpress/agent-skills --skill wp-block-themes- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads wp-block-themes automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
WP Block Themes
When to use
Use this skill for block theme work such as:
- editing
theme.json(presets, settings, styles, per-block styles) - adding or changing templates (
templates/*.html) and template parts (parts/*.html) - adding patterns (
patterns/*.php) and controlling what appears in the inserter - adding style variations (
styles/*.json) - debugging “styles not applying” / “editor doesn’t reflect theme.json”
Inputs required
- Repo root and which theme is targeted (theme directory if multiple exist).
- Target WordPress version range (theme.json version and features vary by core version).
- Where the issue manifests: Site Editor, post editor, frontend, or all.
Procedure
0) Triage and locate block theme roots
- Run triage:
node skills/wp-project-triage/scripts/detect_wp_project.mjs
- Detect theme roots + key folders:
node skills/wp-block-themes/scripts/detect_block_themes.mjs
If multiple themes exist, pick one and scope all changes to that theme root.
1) Create a new block theme (if needed)
If you are creating a new block theme from scratch (or converting a classic theme):
- Prefer starting from a known-good scaffold (or exporting from a WP environment) rather than guessing file layout.
- Be explicit about the minimum supported WordPress version because
theme.jsonschema versions differ.
Read:
references/creating-new-block-theme.md
After creating the theme root, re-run detect_block_themes and continue below.
2) Confirm theme type and override expectations
- Block theme indicators:
theme.jsonpresenttemplates/and/orparts/present
- Remember the style hierarchy:
- core defaults → theme.json → child theme → user customizations
- user customizations can make theme.json edits appear “ignored”
Read:
references/debugging.md(style hierarchy + fastest checks)
3) Make theme.json changes safely
Decide whether you are changing:
- settings (what the UI allows): presets, typography scale, colors, layout, spacing
- styles (how it looks by default): CSS-like rules for elements/blocks
Read:
references/theme-json.md
4) Templates and template parts
- Templates live under
templates/and are HTML. - Template parts live under
parts/and must not be nested in subdirectories.
Read:
references/templates-and-parts.md
5) Patterns
Prefer filesystem patterns under patterns/ when you want theme-owned patterns.
Read:
references/patterns.md
6) Style variations
Style variations are JSON files under styles/. Note: once a user picks a style variation, that selection is stored in the DB, so changing the file may not “update what the user sees” automatically.
Read:
references/style-variations.md
Verification
- Site Editor reflects changes where expected (Styles UI, templates, patterns).
- Frontend renders with expected styles.
- If styles aren’t changing, confirm whether user customizations override theme defaults.
- Run the repo’s build/lint scripts if assets are involved (fonts, custom JS/CSS build).
Failure modes / debugging
Start with:
references/debugging.md
Common issues:
- wrong theme root (editing an inactive theme)
- user customizations override your defaults
- invalid
theme.jsonshape/typos prevent application - templates/parts in wrong folders (or nested parts)
Escalation
If upstream behavior is unclear, consult canonical docs:
- Theme Handbook and Block Editor Handbook for
theme.json, templates, patterns, and style variations.
FAQ
What does the wp-block-themes skill do?
Use when developing WordPress block themes: theme.json (global settings/styles), templates and template parts, patterns, style variations, and Site Editor troubleshooting (style hierarchy, overrides, caching).
How do I install wp-block-themes?
Run npx skills add https://github.com/wordpress/agent-skills --skill wp-block-themes in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/wp-block-themes/ (personal) or .claude/skills/wp-block-themes/ (project).
Which AI agents can use wp-block-themes?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is wp-block-themes safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed; Runlayer flagged items to review; ZeroLeaks passed. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains wp-block-themes?
It is published by wordpress in wordpress/agent-skills, and it is an official skill from the maker of the technology it covers. It has 5,864 recorded installs.
More from wordpress/agent-skills
wp-plugin-development
wordpress/agent-skills
Use when developing WordPress plugins: architecture and hooks, activation/deactivation/uninstall, admin UI and Settings API, data storage, cron/tasks, security (nonces/capabilities/sanitization/escaping), and release packaging.
wp-performance
wordpress/agent-skills
Use when investigating or improving WordPress performance (backend-only agent): profiling and measurement (WP-CLI profile/doctor, Server-Timing, Query Monitor via REST headers), database/query optimization, autoloaded options, object caching, cron, HTTP API calls, and safe verification.
wp-rest-api
wordpress/agent-skills
Use when building, extending, or debugging WordPress REST API endpoints/routes: registerrestroute, WPRESTController/controller classes, schema/argument validation, permissioncallback/authentication, response shaping, registerrestfield/registermeta, or exposing CPTs/taxonomies via showinrest.
wordpress-router
wordpress/agent-skills
Use when the user asks about WordPress codebases (plugins, themes, block themes, Gutenberg blocks, WP core checkouts) and you need to quickly classify the repo and route to the correct workflow/skill (blocks, theme.json, REST API, WP-CLI, performance, security, testing, release packaging).
wp-block-development
wordpress/agent-skills
Use when developing WordPress (Gutenberg) blocks: block.json metadata, registerblocktype(frommetadata), attributes/serialization, supports, dynamic rendering (render.php/rendercallback), deprecations/migrations, viewScript vs viewScriptModule, and @wordpress/scripts/@wordpress/create-block build and test workflows.
wp-wpcli-and-ops
wordpress/agent-skills
Use when working with WP-CLI (wp) for WordPress operations: safe search-replace, db export/import, plugin/theme/user/content management, cron, cache flushing, multisite, and scripting/automation with wp-cli.yml.
Popular frontend & design skills
setup-matt-pocock-skills
mattpocock/skills
Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
frontend-design
anthropics/skills
Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
hyperframes-animation
heygen-com/hyperframes
All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.
prototype
mattpocock/skills
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
hyperframes-core
heygen-com/hyperframes
The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.
vercel-react-best-practices
vercel-labs/agent-skills
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.