Teach your coding agent to write WordPress Playground Blueprints – WordPress Playground
Skip to content
WordPress Playground
The new
blueprint agent skill
teaches your coding agent the Playground Blueprint schema, which defines valid property names, resource types, and step sequencing. No more
pluginZipFile
instead of
pluginData
. No more
runPHP
steps missing
require '/wordpress/wp-load.php'
Install it once, and your agent generates valid Blueprint
JSON
JSON
JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML.
with a high success rate, and the best part of it all with natural language. That is perfect for testing new ideas, finding edge cases in your Plugins and Themes, and creating demos from your projects.
What the blueprint skill does
The skill is a structured Markdown reference that your coding agent loads into its context. It covers:
Every top-level property
landingPage
preferredVersions
features
steps
, shorthands (
plugins
siteOptions
constants
All resource types
wordpress.org/plugins
wordpress.org/themes
url
git:directory
literal:directory
bundled
Step reference
installPlugin
writeFile
writeFiles
runPHP
wp-cli
runSql
, and more
Common mistakes
: a table of pitfalls the agent checks against before generating output
Blueprint bundles
: self-contained packages with bundled resources
The agent reads this reference before writing any Blueprint. Instead of guessing property names, it follows the documented schema.
How to install the skill
For a quick install, use the
npx skills
CLI
CLI
Command Line Interface. Terminal (Bash) in Mac, Command Prompt in Windows, or WP-CLI for WordPress.
to add the blueprint skill to your project:
npx skills add wordpress/agent-skills --skill blueprint
Or install manually by cloning the
agent-skills repository
and running the build script:
git clone https://github.com/WordPress/agent-skills.git
cd agent-skills
node shared/scripts/skillpack-build.mjs --clean
node shared/scripts/skillpack-install.mjs --dest=../your-wp-project --targets=claude,gemini,codex,cursor,vscode
The skill works with Claude Code, Gemini CLI,
GitHub
GitHub
GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged by the repository owner.
Copilot, Cursor, and Codex.
Five examples
Each example below shows a prompt you give your agent and the Blueprint it produces. These are real-world scenarios where the blueprint skill prevents common errors.
1. Quick development environment
Prompt:
Create a Blueprint that sets up a development environment with
debug mode, the Developer plugin, and landing on the admin dashboard.
Generated Blueprint:
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
"landingPage": "/wp-admin/",
"preferredVersions": { "php": "8.3", "wp": "latest" },
"features": { "networking": true },
"constants": {
"WP_DEBUG": true,
"WP_DEBUG_LOG": true
},
"login": true,
"plugins": ["developer"],
"steps": []
Notice how the agent uses the
constants
shorthand instead of a
defineWpConfigConsts
step, and
login: true
instead of a separate login step. The skill teaches agents to pick shorthands for simple cases and explicit steps when order matters.
2.
Plugin
Plugin
A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory
or can be cost-based plugin from a third-party.
from a GitHub branch
Prompt:
Write a Blueprint that installs my plugin from the feature/checkout-v2
branch on GitHub and activates it.
Generated Blueprint:
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
"landingPage": "/wp-admin/plugins.php",
"preferredVersions": { "php": "8.3", "wp": "latest" },
"steps": [
{ "step": "login" },
"step": "installPlugin",
"pluginData": {
"resource": "git:directory",
"url": "https://github.com/your-org/your-plugin",
"ref": "feature/checkout-v2",
"refType": "branch",
"path": "/"
},
"options": { "activate": true }
Without the skill, agents commonly omit
refType
, which causes
git:directory
to fail for branch names. The skill’s common mistakes table flags this explicitly: “Omitting
refType
with branch/tag
ref
— required; only
HEAD
works without it.”
3. WooCommerce store with sample products
Prompt:
Create a Blueprint for a WooCommerce store with 5 sample products
across 2 categories, running on PHP 8.2.
Generated Blueprint:
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
"landingPage": "/shop/",
"preferredVersions": { "php": "8.2", "wp": "latest" },
"features": { "networking": true },
"steps": [
{ "step": "login" },
"step": "installPlugin",
"pluginData": { "resource": "wordpress.org/plugins", "slug": "woocommerce" },
"options": { "activate": true }
},
"step": "runPHP",
"code": " $title,\n 'post_type' => 'product',\n 'post_status' => 'publish'\n ]);\n update_post_meta($post_id, '_regular_price', $price);\n update_post_meta($post_id, '_price', $price);\n wp_set_object_terms($post_id, [$cat_id], 'product_cat');\n}\n"
The skill ensures the agent includes
require '/wordpress/wp-load.php'
at the top of every
runPHP
step. Without this line, all WordPress functions fail silently — a mistake agents make frequently without the skill reference.
4. Inline mu-plugin for custom behavior
Prompt:
Write a Blueprint that disables the admin bar and adds a custom
dashboard widget showing the server's PHP version.
Generated Blueprint:
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
"landingPage": "/wp-admin/",
"preferredVersions": { "php": "8.3", "wp": "latest" },
"steps": [
{ "step": "login" },
"step": "writeFile",
"path": "/wordpress/wp-content/mu-plugins/custom-dashboard.php",
"data": "Running PHP ' . phpversion() . '
The agent uses
writeFile
to create a
mu-plugin
, which loads automatically without activation. The skill explicitly documents this pattern and warns agents not to add
require wp-load.php
inside mu-plugin code (that line is only needed in
runPHP
steps).
5. Blueprint bundle with a custom plugin
Prompt:
Create a Blueprint bundle that installs a custom analytics plugin
from a local zip file.
Generated bundle structure:
analytics-bundle/
├── blueprint.json
└── analytics-plugin.zip
blueprint.json:
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
"landingPage": "/wp-admin/plugins.php",
"preferredVersions": { "php": "8.3", "wp": "latest" },
"steps": [
{ "step": "login" },
"step": "installPlugin",
"pluginData": {
"resource": "bundled",
"path": "/analytics-plugin.zip"
},
"options": { "activate": true }
Run it locally:
npx @wp-playground/cli server --blueprint=./analytics-bundle/ --blueprint-may-read-adjacent-files
The
--blueprint-may-read-adjacent-files
flag is required for directory bundles. Without it, any
bundled
resource reference fails with a “File not found” error. The skill documents this gotcha, so agents include the flag automatically.
How the blueprint skill fits with other tools
The blueprint skill works alongside two other Playground tools for AI agents:
Tool
What it does
When to use it
Blueprint skill
Generates valid Blueprint JSON
When you need a Blueprint file for sharing, version control, or CI
wp-playground skill
Runs CLI commands, manages servers, debugs instances
When you need a running Playground instance with live interaction
MCP server
Connects agents directly to a browser Playground
When you need real-time
PHP
PHP
PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML.
execution and file manipulation
Use the blueprint skill when you want a portable, reproducible configuration. Use the wp-playground skill when you need a running server. Combine them: generate a Blueprint with the blueprint skill, then launch it with the wp-playground skill’s CLI commands.
Test your Blueprints
Inline
URL
URL
A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org
(quick test)
Minify the Blueprint JSON and append it to the Playground URL:
Local CLI (full test)
# Start a server with your Blueprint
npx @wp-playground/cli server --blueprint=./blueprint.json
# Headless validation (runs and exits)
npx @wp-playground/cli run-blueprint --blueprint=./blueprint.json
Get started
Install the blueprint skill in your project:
npx skills add wordpress/agent-skills --skill blueprint
Then ask your agent to write a Blueprint. Describe what you need: plugins, themes, content, configuration, and the agent produces valid JSON that runs on the first try.
Share what you build in the
playground
channel on
Making WordPress Slack
or open an issue on
GitHub
agent-skills
ai
Share this:
Share on Threads (Opens in new window)
Threads
Share on Mastodon (Opens in new window)
Mastodon
Share on Bluesky (Opens in new window)
Bluesky
Share on Facebook (Opens in new window)
Share on X (Opens in new window)
Share on LinkedIn (Opens in new window)
Leave a Reply
Cancel reply
You must be
logged in
to post a comment.
Site resources
Links
WordPress Playground page
Playground documentation
Contributing to WordPress Playground
Email Updates
Enter your email address to subscribe to this blog and receive notifications of new posts by email.
Join 16 other subscribers
Meetings
Join us in the
#playground
channel
Playground Team Meeting
Fri May 8 14:00:00 2026 UTC
(2 weeks from now) accessible via
#playground
on Slack
Recent Posts
X-post: WordPress Core Dev Environment Toolkit: A Faster Path to Your First Core Contribution
Migrating WordPress Playground Documentation to WordPress.org
Teach your coding agent to write WordPress Playground Blueprints
Playground Meetings Summaries – March 2026
Connect AI coding agents to WordPress Playground with MCP
Recent Comments
Archives
April 2026
March 2026
February 2026
January 2026
December 2025
November 2025
October 2025
August 2025
July 2025
June 2025
December 2024
November 2024
October 2024
September 2024
August 2024
Categories
Meetings
status
Updates
Recent Updates
Recent Comments
No Replies
Recent Activity
Team Pledges
155 people
have pledged time to contribute to Playground Team efforts! When looking for help on a project or program, try starting by reaching out to them!
compose new post
reply
edit
go to top
go to the next post or comment
go to the previous post or comment
toggle comment visibility
esc
cancel edit post or comment
%d