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 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, 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.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 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.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