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.

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 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 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 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 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 ): File Operations data accepts a plain string (as shown above) or a resource reference (e.g. { "resource": "url", "url": "https://..." } ). 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: GOTCHA: You must require '/wordpress/wp load.php'; to use any WordPress functions. wp cli: The step name is wp cli (with hyphen), NOT cli or wpcli . runSql: Site Configuration 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) Inline plugin with multiple files Then activate it with a separate step: Plugin from a GitHub branch 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: Blueprint docs: https://wordpress.github.io/wordpress playground/blueprints JSON schema: https://playground.wordpress.net/blueprint schema.json 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 Plugins and themes must be zipped before bundling — installPlugin expects a zip, not a raw directory. To create the zip from a plugin directory: Referencing Bundled Resources Use the bundled resource type to reference files within the bundle: 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: 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: 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): Headless validation (runs blueprint and exits): 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 .