Index of every page on this site: llms.txt
All skills
wordpress avatar

/blueprint

@7374e6f official
by wordpresswordpress/agent-skills2.4k stars
351
Run it yourself

Use when the deliverable is WordPress Playground Blueprint JSON or a Blueprint bundle, including creating, editing, reviewing, validating schema keys, choosing steps/resources, and debugging Blueprint files. For only running or sharing a Playground environment, use wp-playground.

Use this Skill: https://skilld.dev/gh/wordpress/agent-skills/blueprint

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈73 tokens for metadata: the name and description. ≈4k when used: this file.

Description uses 3.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈292 characters, or 3.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

WordPress Playground Blueprints

Overview

A Blueprint is a JSON file that declaratively configures a WordPress Playground instance — installing plugins/themes, setting options, running PHP/SQL, manipulating files, and more.

Core principle: Blueprints are trusted JSON-only declarations. No arbitrary JavaScript. They work on web, Node.js, and CLI.

Quick Start Template

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/wp-admin/",
  "preferredVersions": { "php": "8.3", "wp": "latest" },
  "steps": [{ "step": "login" }]
}

Top-Level Properties

All optional. Only documented keys are allowed — the schema rejects unknown properties.

Property Type Notes
$schema string Always "https://playground.wordpress.net/blueprint-schema.json"
landingPage string Relative path, e.g. /wp-admin/
description string Deprecated optional top-level description. Prefer meta.description for new Blueprints
meta object { title, author, description?, categories? } — title and author required
preferredVersions object { php, wp } — both required when present
features object { networking?: boolean, intl?: boolean } — only these two keys, nothing else. Networking defaults to true
phpExtensionBundles any Deprecated/no longer used; the schema leaves the value unconstrained and says to remove it from Blueprints
extraLibraries array ["wp-cli"] — auto-included when any wp-cli step is present
constants object Shorthand for defineWpConfigConsts. Values: string/boolean/number
plugins array Shorthand for installPlugin steps. Strings = wp.org slugs
siteOptions object Shorthand for setSiteOptions
login boolean or object true = login as admin. Object = { username?, password? } (both default to "admin"/"password")
steps array Main execution pipeline. Runs after shorthands

preferredVersions Values

  • php: Major.minor only: "7.4", "8.0", "8.1", "8.2", "8.3", "8.4", "8.5", or "latest". Patch versions like "7.4.1" are invalid. Check the schema for currently supported versions.
  • wp: Recent major versions, "latest", "beta", "nightly"/"trunk", or a URL to a custom zip. The schema also accepts false for PHP-only Playground; do not combine wp: false with WordPress-only fields such as plugins, siteOptions, login, or WordPress-only steps.

Shorthands vs Steps

Shorthands (login, plugins, siteOptions, constants) are expanded and prepended to steps in an unspecified order. Use explicit steps when execution order matters.

Resource References

Resources tell Playground where to find files. Used by installPlugin, installTheme, writeFile, writeFiles, importWxr, etc.

Resource Type Required Fields Example
wordpress.org/plugins slug { "resource": "wordpress.org/plugins", "slug": "woocommerce" }
wordpress.org/themes slug { "resource": "wordpress.org/themes", "slug": "astra" }
url url { "resource": "url", "url": "https://example.com/plugin.zip" }
git:directory url, ref See below
literal name, contents { "resource": "literal", "name": "file.txt", "contents": "hello" }
literal:directory name, files See below
bundled path References a file within a blueprint bundle (e.g. { "resource": "bundled", "path": "/plugin.zip" })
zip inner Wraps another resource in a ZIP — use when a step expects a zip but your source isn't one (e.g. wrapping a url resource pointing to a raw directory)

git:directory — Installing from GitHub

{
  "resource": "git:directory",
  "url": "https://github.com/WordPress/gutenberg",
  "ref": "trunk",
  "refType": "branch",
  "path": "/"
}
  • When using a branch or tag name for ref, you must set refType ("branch" | "tag" | "commit" | "refname"). Without it, only "HEAD" resolves reliably.
  • path selects a subdirectory (defaults to repo root).

literal:directory — Inline File Trees

{
  "resource": "literal:directory",
  "name": "my-plugin",
  "files": {
    "plugin.php": "<?php /* Plugin Name: My Plugin */ ?>",
    "includes": {
      "helper.php": "<?php // helper code ?>"
    }
  }
}
  • files uses nested objects for subdirectories — keys are filenames or directory names, values are plain strings (file content) or objects (subdirectories). Never use resource references as values.
  • Do NOT use path separators in keys (e.g. "includes/helper.php" is wrong — use a nested "includes": { "helper.php": "..." } object).

Steps Reference

Every step requires "step": "<name>". Any step can optionally include "progress": { "weight": 1, "caption": "Installing..." } for UI feedback.

Plugin & Theme Installation

{
  "step": "installPlugin",
  "pluginData": { "resource": "wordpress.org/plugins", "slug": "gutenberg" },
  "options": { "activate": true, "targetFolderName": "gutenberg" },
  "ifAlreadyInstalled": "overwrite"
}
{
  "step": "installTheme",
  "themeData": { "resource": "wordpress.org/themes", "slug": "twentytwentyfour" },
  "options": { "activate": true, "importStarterContent": true },
  "ifAlreadyInstalled": "overwrite"
}
  • Use pluginData / themeData — NOT the deprecated pluginZipFile / themeZipFile.
  • pluginData / themeData accept any FileReference or DirectoryReference — a zip URL, a wordpress.org/plugins slug, a git:directory, or a literal:directory (no zip wrapper needed).
  • options.activate controls activation. No need for a separate activatePlugin/activateTheme step when using installPlugin/installTheme.
  • ifAlreadyInstalled: "overwrite" | "skip" | "error"

Activation (standalone)

Only needed for plugins/themes already on disk (e.g. after writeFile/writeFiles):

{ "step": "activatePlugin", "pluginPath": "my-plugin/my-plugin.php" }
{ "step": "activateTheme", "themeFolderName": "twentytwentyfour" }

File Operations

{ "step": "writeFile", "path": "/wordpress/wp-content/mu-plugins/custom.php", "data": "<?php // code" }

data accepts a plain string (as shown above) or a resource reference (e.g. { "resource": "url", "url": "https://..." }).

{
  "step": "writeFiles",
  "writeToPath": "/wordpress/wp-content/plugins/",
  "filesTree": {
    "resource": "literal:directory",
    "name": "my-plugin",
    "files": {
      "plugin.php": "<?php\n/*\nPlugin Name: My Plugin\n*/",
      "includes": {
        "helpers.php": "<?php // helpers"
      }
    }
  }
}

writeFiles requires a DirectoryReference (literal:directory or git:directory) as filesTree — not a plain object.

Other file operations: mkdir, cp, mv, rm, rmdir, unzip.

Running Code

runPHP:

{ "step": "runPHP", "code": "<?php require '/wordpress/wp-load.php'; update_option('key', 'value');" }

GOTCHA: You must require '/wordpress/wp-load.php'; to use any WordPress functions.

wp-cli:

{ "step": "wp-cli", "command": "wp post create --post_type=page --post_title='Hello' --post_status=publish" }

The step name is wp-cli (with hyphen), NOT cli or wpcli.

runSql:

{ "step": "runSql", "sql": { "resource": "literal", "name": "q.sql", "contents": "UPDATE wp_options SET option_value='val' WHERE option_name='key';" } }

Site Configuration

{ "step": "setSiteOptions", "options": { "blogname": "My Site", "blogdescription": "A tagline" } }
{ "step": "defineWpConfigConsts", "consts": { "WP_DEBUG": true } }
{ "step": "setSiteLanguage", "language": "en_US" }
{ "step": "defineSiteUrl", "siteUrl": "https://example.com" }

Other Steps

Step Key Properties
login username?, password? (default "admin" / "password")
enableMultisite (no required props)
importWxr file (FileReference)
importThemeStarterContent themeSlug?
importWordPressFiles wordPressFilesZip, pathInZip? — imports a full WordPress directory from a zip
request request: { url, method?, headers?, body? }
updateUserMeta userId, meta
runWpInstallationWizard options? — runs the WP install wizard with given options
resetData (no props)

Common Patterns

Inline mu-plugin (quick custom code)

{
  "step": "writeFile",
  "path": "/wordpress/wp-content/mu-plugins/custom.php",
  "data": "<?php\n// mu-plugins load automatically — no activation needed, no require wp-load.php\nadd_filter('show_admin_bar', '__return_false');"
}

Inline plugin with multiple files

{
  "step": "writeFiles",
  "writeToPath": "/wordpress/wp-content/plugins/",
  "filesTree": {
    "resource": "literal:directory",
    "name": "my-plugin",
    "files": {
      "my-plugin.php": "<?php\n/*\nPlugin Name: My Plugin\n*/\nrequire __DIR__ . '/includes/main.php';",
      "includes": {
        "main.php": "<?php // main logic"
      }
    }
  }
}

Then activate it with a separate step:

{ "step": "activatePlugin", "pluginPath": "my-plugin/my-plugin.php" }

Plugin from a GitHub branch

{
  "step": "installPlugin",
  "pluginData": {
    "resource": "git:directory",
    "url": "https://github.com/user/repo",
    "ref": "feature-branch",
    "refType": "branch",
    "path": "/"
  }
}

Common Mistakes

Mistake Correct
pluginZipFile / themeZipFile pluginData / themeData
"step": "cli" "step": "wp-cli"
Flat object as writeFiles.filesTree Must be a literal:directory or git:directory resource
Path separators in files keys Use nested objects for subdirectories
runPHP without wp-load.php Always require '/wordpress/wp-load.php'; for WP functions
Invented top-level keys Only documented keys work — schema rejects unknown properties
Inventing proxy URLs for GitHub Use git:directory resource type
Omitting refType with branch/tag ref Required — only "HEAD" works without it
Resource references in literal:directory files values Values must be plain strings (content) or objects (subdirectories) — never resource refs
features.debug or other invented feature keys features only supports networking and intl — use constants: { "WP_DEBUG": true } for debug mode
require wp-load.php in mu-plugin code Only needed in runPHP steps — mu-plugins already run within WordPress
Schema URL with .org domain Must be playground.wordpress.net, not playground.wordpress.org

Full Reference

This skill covers the most common steps and patterns. For the complete API, see:

Additional steps not covered above: runPHPWithOptions (run PHP with custom ini settings), runWpInstallationWizard, and resource types vfs and bundled (for advanced embedding scenarios).

Blueprint Bundles

Bundles are self-contained packages that include a blueprint.json along with all the resources it references (plugins, themes, WXR files, etc.). Instead of hosting assets externally, bundle them alongside the blueprint.

Bundle Structure

my-bundle/
├── blueprint.json          ← must be at the root
├── my-plugin.zip           ← zipped plugin directory
├── theme.zip
└── content/
    └── sample-content.wxr

Plugins and themes must be zipped before bundling — installPlugin expects a zip, not a raw directory. To create the zip from a plugin directory:

cd my-bundle
zip -r my-plugin.zip my-plugin/

Referencing Bundled Resources

Use the bundled resource type to reference files within the bundle:

{
  "step": "installPlugin",
  "pluginData": {
    "resource": "bundled",
    "path": "/my-plugin.zip"
  },
  "options": { "activate": true }
}
{
  "step": "importWxr",
  "file": {
    "resource": "bundled",
    "path": "/content/sample-content.wxr"
  }
}

Creating a Bundle Step by Step

  1. Create the bundle directory and add blueprint.json at its root.
  2. Write your plugin/theme source files in a subdirectory (e.g. my-plugin/my-plugin.php).
  3. Zip the plugin directory: zip -r my-plugin.zip my-plugin/
  4. Reference it in blueprint.json using { "resource": "bundled", "path": "/my-plugin.zip" }.

Full example — a bundle that installs a custom plugin:

dashboard-widget-bundle/
├── blueprint.json
├── dashboard-widget.zip        ← zip of dashboard-widget/
└── dashboard-widget/           ← plugin source (kept for editing)
    └── dashboard-widget.php
{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/wp-admin/",
  "preferredVersions": { "php": "8.3", "wp": "latest" },
  "steps": [
    { "step": "login" },
    {
      "step": "installPlugin",
      "pluginData": { "resource": "bundled", "path": "/dashboard-widget.zip" },
      "options": { "activate": true }
    }
  ]
}

Distribution Formats

Format How to use
ZIP file (remote) Website: https://playground.wordpress.net/?blueprint-url=https://example.com/bundle.zip
ZIP file (local) CLI: npx @wp-playground/cli server --blueprint=./bundle.zip
Local directory CLI: npx @wp-playground/cli server --blueprint=./my-bundle/ --blueprint-may-read-adjacent-files
Git repository directory Point blueprint-url at a repo directory containing blueprint.json

GOTCHA: Local directory bundles always need --blueprint-may-read-adjacent-files for the CLI to read bundled resources. Without it, any "resource": "bundled" reference will fail with a "File not found" error. ZIP bundles don't need this flag — all files are self-contained inside the archive.

Testing Blueprints

Inline Blueprints (quick test, no bundles)

Minify the blueprint JSON (no extra whitespace), encode it once with encodeURIComponent(), prepend https://playground.wordpress.net/#, and open the URL in a browser:

https://playground.wordpress.net/#%7B%22%24schema%22%3A%22https%3A%2F%2Fplayground.wordpress.net%2Fblueprint-schema.json%22%2C%22preferredVersions%22%3A%7B%22php%22%3A%228.3%22%2C%22wp%22%3A%22latest%22%7D%2C%22steps%22%3A%5B%7B%22step%22%3A%22login%22%7D%5D%7D

Very large blueprints may exceed browser URL length limits; use the CLI or a hosted Blueprint URL instead. For share-link details, use wp-playground/references/website.md.

Local CLI Testing

Interactive server (keeps running, opens in browser):

# Directory bundle — requires --blueprint-may-read-adjacent-files
npx @wp-playground/cli server --blueprint=./my-bundle/ --blueprint-may-read-adjacent-files

# ZIP bundle — self-contained, no extra flags needed
npx @wp-playground/cli server --blueprint=./bundle.zip

Headless validation (runs blueprint and exits):

npx @wp-playground/cli run-blueprint --blueprint=./my-bundle/ --blueprint-may-read-adjacent-files

Testing with WordPress Playground

Use the wp-playground skill for local or browser testing. For CLI testing, follow wp-playground/references/cli.md with --blueprint=<path-or-url>; for directory bundles, pass --blueprint-may-read-adjacent-files.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo4 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill provides official documentation for the WordPress Playground Blueprint JSON format, authored by WordPress. It describes powerful but standard features of the environment, including PHP execution, WP-CLI command support, and the ability to install assets from external URLs and Git repositories. These capabilities are consistent with the skill's primary purpose of configuring sandbox WordPress instances and utilize trusted WordPress-managed domains.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 7374e6f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 4 months ago
compatibility
WordPress 7.0+, PHP 7.4.0+. Optionally Playground CLI or a browser
  • wordpress
  • playground
  • blueprint
  • json
  • configuration
  • plugins
  • themes
  • php
  • wp-cli
  • multisite

README badge

README badge for wordpress/agent-skills/blueprint

Generates WordPress Playground blueprint JSON files that declaratively configure demo instances with plugins, themes, PHP code, and site settings. Covers the full Blueprint API including resource references, step definitions, common patterns, and schema validation rules for WordPress 6.9+ environments.

Generated from the current SKILL.md.

Can I use variables or dynamic values in a blueprint?
No. Blueprints are static JSON declarations with no JavaScript execution or variable substitution. All values must be hardcoded.
What PHP and WordPress versions does this skill support?
WordPress 6.9+ and PHP 7.2.24+. Specific supported versions for `preferredVersions` are listed in the JSON schema at https://playground.wordpress.net/blueprint-schema.json.
How do I install a plugin from a GitHub branch rather than wordpress.org?
Use the `git:directory` resource type with `ref` and `refType` properties. For example: `{ "resource": "git:directory", "url": "https://github.com/user/repo", "ref": "feature-branch", "refType": "branch", "path": "/" }`.
Do I need to set `refType` when specifying a `ref` in a git:directory resource?
Yes. When using a branch or tag name, you must set `refType` to `"branch"`, `"tag"`, `"commit"`, or `"refname"`. Without it, only `"HEAD"` resolves reliably.
What is the difference between shorthands like `plugins` and explicit `installPlugin` steps?
Shorthands are expanded and prepended to the `steps` array in unspecified order. Use explicit steps when execution order matters, such as when code depends on a plugin being installed first.

Generated from the current SKILL.md. These answers refresh after source changes.