What are the WordPress agent skills?
WordPress agent skills is the WordPress project's own bundle of portable skill folders for AI coding assistants. Each folder holds a SKILL.md procedure, reference notes and helper scripts. The wp-block-themes skill covers theme.json, templates, template parts, patterns and style variations, so the agent stops guessing at theme structure.
This repository packages WordPress development knowledge as skill folders. The README says AI assistants often produce outdated patterns from before block themes, skip security checks and cause invalid block errors, and each skill is written to prevent that.
Each skill is a self-contained folder. It carries a SKILL.md with when to use it, the procedure and verification, a references folder for deep topics, and optional scripts for detection and validation.
What changes in your agent's output
- Theme work starts with a triage script that detects the project type, tooling and versions, instead of assuming a layout.
- Changes to theme.json are split into settings, which control what the editor allows, and styles, which set the default look.
- Templates live in the templates folder, and template parts sit in the parts folder with no nesting.
- The agent checks whether user customizations in the Site Editor override theme defaults before it blames the file.
- Block work follows block.json, attributes, rendering and deprecations, so older markup does not break.
Who it is for
Best for
- Developers building or converting block themes who want the agent to follow the official theme.json and template rules.
- Teams that maintain plugins and themes in the same repository and want one router skill to pick the right workflow.
- Agencies that want a shared, committable skills folder so every developer's agent behaves the same way.
Not for
- Visual design direction. The skills cover WordPress structure and APIs, not typography or colour taste.
- Sites on WordPress older than the targeted range. The README states compatibility with WordPress 7.0 and PHP 7.4.0 or newer.
- Anyone who expects a finished theme from one prompt. These skills guide the agent, they do not generate a site.
Use it with UiChemy
Skills help the agent write WordPress code, while UiChemy handles design to page work. Figma to WordPress converts a design file, and Composer edits the result in Elementor or Gutenberg. Click Get Started on uichemy.com.
How to install WordPress Agent Skills: Block Theme and theme.json Rules for AI Agents
git clone https://github.com/WordPress/agent-skills.gitThe README targets WordPress 7.0 or newer and PHP 7.4.0 or newer, and says the skills were AI generated from official docs and then reviewed by contributors.Clone the repository
Run the clone command above and move into the folder. The skills sit under the skills directory.
Build the distribution
Run
node shared/scripts/skillpack-build.mjs --clean. The README lists this as the first step for the packaged install.Install into your project
Run
node shared/scripts/skillpack-install.mjs --dest=../your-wp-project --targets=codex,vscode,claude,cursor. This copies skills into .codex, .github, .claude and .cursor skill folders.Or install globally
Add the global flag to install into your home skills folder, or pick single skills with the skills option. The README also allows copying one skill folder by hand.
Check that it loaded
Ask your agent to add a style variation to a block theme. It should run the triage and detect scripts, edit files under styles, and warn that a stored user choice can hide file changes.
Key features
- wordpress-routerClassifies a WordPress repository and routes the agent to the right workflow, so a theme task does not get plugin advice.
- wp-project-triageDetects project type, tooling and versions automatically with a script before any change is made.
- wp-block-themesCovers theme.json, templates, template parts, patterns and style variations, plus debugging of the style hierarchy.
- wp-block-developmentGutenberg block work: block.json, attributes, rendering and deprecations that prevent Invalid block errors.
- wp-plugin-developmentPlugin architecture, hooks, the Settings API and security practice for plugin code.
- wp-rest-api and wp-interactivity-apiRoutes, schema and authentication for REST, plus data-wp directives and stores for frontend interactivity.
- wp-performance and wp-wpcli-and-opsProfiling, caching and Server-Timing, along with WP-CLI commands, automation and search-replace.
- wp-playground, blueprint and wp-envRun and preview a site in WordPress Playground, describe environments with Blueprints, or use a local wp-env setup.
- wpdsA skill for the WordPress Design System, listed alongside the plugin directory guidelines skill.
- Validation scriptsA validate command checks skill metadata and the project triage report, though it does not run the eval scenarios.
Frequently asked questions
What are WordPress agent skills?
They are portable bundles of instructions, checklists and scripts from the WordPress project. An AI assistant reads them while working on WordPress code and follows the documented procedure for blocks, themes, plugins, REST routes and operations instead of guessing from older training data.
What does the wp-block-themes skill cover?
It covers editing theme.json, adding templates and template parts, writing patterns, and creating style variations. It also gives a debugging path for styles that do not apply, including the style hierarchy where user customizations in the Site Editor override theme defaults.
How do I install the WordPress agent skills?
Clone the repository, run the skillpack build script, then run the install script with a destination folder and targets such as codex, vscode, claude or cursor. You can also install globally, or copy a single skill folder into your agent's instructions directory by hand.
Which AI agents do the WordPress agent skills work with?
The README names Claude, Copilot, Codex and Cursor, and lists install targets for Codex, VS Code with GitHub Copilot, Claude Code and Cursor, with Antigravity as an opt-in. It says they work with any assistant that supports project-level instructions.
Can these skills build a whole block theme for me?
They guide the agent rather than generate a site. The block themes skill tells it how to create or convert a theme and which files to edit, but you still review the result. For a themed workflow with design previews, see wp-theme-development.
Which WordPress versions do the skills target?
The README states compatibility with WordPress 7.0 or newer and PHP 7.4.0 or newer. If your site runs an older release, check each skill's compatibility note before relying on its theme.json or block guidance.
Are the skills written by people or by AI?
The README discloses that the skills were generated with GPT-5.2 Codex from official Gutenberg and WordPress documentation, then reviewed and edited by WordPress contributors. It calls this a first version that will improve as the community contributes fixes.
What should I use for converting an HTML project to a block theme?
The WordPress skills explain theme structure and the files involved, but a dedicated converter such as wp-block-theme-converter targets that one job directly. For Tailwind styling inside your theme, see tailwind-design-system as a companion skill.


