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 JSONJSON 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 (login,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 CLICLI 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 blueprintOr 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,vscodeThe skill works with Claude Code, Gemini CLI, GitHubGitHub 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. https://github.com/ 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. PluginPlugin 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 https://wordpress.org/plugins/ 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": "<?php\nrequire '/wordpress/wp-load.php';\n\n// Create categories\n$cat_clothing = wp_insert_term('Clothing', 'product_cat');\n$cat_accessories = wp_insert_term('Accessories', 'product_cat');\n\n$products = [\n ['T-Shirt', 29.99, $cat_clothing['term_id']],\n ['Hoodie', 59.99, $cat_clothing['term_id']],\n ['Jeans', 49.99, $cat_clothing['term_id']],\n ['Watch', 89.99, $cat_accessories['term_id']],\n ['Backpack', 39.99, $cat_accessories['term_id']]\n];\n\nforeach ($products as [$title, $price, $cat_id]) {\n $post_id = wp_insert_post([\n 'post_title' => $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": "<?php\nadd_filter('show_admin_bar', '__return_false');\n\nadd_action('wp_dashboard_setup', function() {\n wp_add_dashboard_widget(\n 'php_version_widget',\n 'PHP Version',\n function() {\n echo '<p>Running PHP ' . phpversion() . '</p>';\n }\n );\n});"
}
]
}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.zipblueprint.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-filesThe --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 PHPPHP 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. https://www.php.net/manual/en/preface.php 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 URLURL 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:
https://playground.wordpress.net/#{"preferredVersions":{"php":"8.3","wp":"latest"},"steps":[{"step":"login"}]}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.jsonGet started
Install the blueprint skill in your project:
npx skills add wordpress/agent-skills --skill blueprintThen 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.