Blueprint
Spin up reproducible WordPress Playground demos from JSON blueprints for plugin reviews, client pitches, and contributor onboarding.
Overview
Blueprint is an agent skill most often used in Validate (also Build docs, Launch distribution) that creates and reviews WordPress Playground blueprint JSON for reproducible demo environments.
Install
npx skills add https://github.com/wordpress/agent-skills --skill blueprintWhat is this skill?
- JSON-only Blueprint schema—no arbitrary JavaScript; runs on web, Node.js, and CLI
- Top-level controls: `$schema`, landing page, preferred PHP/WP versions, meta, networking/intl features
- Step pipeline for login, install plugins/themes, options, PHP/SQL, and file steps
- Quick-start template with `landingPage` and `preferredVersions` for instant wp-admin demos
- Strict schema rejects unknown keys—safe review surface for agent-generated configs
- Schema URL: https://playground.wordpress.net/blueprint-schema.json
- Documented `features` keys limited to networking and intl when present
Adoption & trust: 969 installs on skills.sh; 1.6k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need a consistent WordPress demo for a plugin or theme but manual Playground clicking does not scale or version-control well.
Who is it for?
Plugin/theme developers and indie consultants who demo WordPress in Playground for validation, support, or marketing.
Skip if: Production WordPress hosting, security hardening on live servers, or sites that require custom PHP outside Playground’s step model.
When should I use this skill?
Creating, editing, or reviewing Playground blueprint JSON; mentions blueprints, playground configuration, or WordPress demo setup.
What do I get? / Deliverables
You ship a schema-valid blueprint JSON that boots the exact Playground instance—versions, steps, and landing page—for sharing or CI-driven previews.
- Valid blueprint JSON with steps and version pins
- Review notes for schema violations or risky steps
- Shareable Playground launch configuration
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Validate because blueprints primarily configure throwaway Playground instances to prove a plugin, theme, or site setup before full hosting commits. Prototype matches declarative demo environments—not production WordPress hardening or long-lived hosting ops.
Where it fits
Blueprint installs your plugin and lands on wp-admin for a 5-minute investor demo.
Embed a playground link on a waitlist page so visitors try the theme safely.
Commit a blueprint beside the plugin so contributors reproduce bugs in one click.
Ship a tagged blueprint release asset for launch-day reviewers.
How it compares
Declarative Playground config skill—not a full WordPress site generator or hosting provisioner.
Common Questions / FAQ
Who is blueprint for?
WordPress creators and solo builders who use Playground to show plugins, themes, or site setups without maintaining a dedicated staging server.
When should I use blueprint?
Use in Validate to prototype a demo for a landing page or pitch; in Build to document reproduction steps in repo docs; and in Launch when sharing a one-click playground link with early users or reviewers.
Is blueprint safe to install?
Blueprints can install plugins, run SQL/PHP steps, and enable networking in sandboxes—review the Security Audits panel on this page and inspect JSON before sharing public demo links.
SKILL.md
READMESKILL.md - Blueprint
# 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 ```json { "$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/` | | `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` | | `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 (e.g. `"8.3"`, `"7.4"`), or `"latest"`. Patch versions like `"7.4.1"` are invalid. Check the schema for currently supported versions. - **wp:** Recent major versions (e.g. `"6.7"`, `"6.8"`), `"latest"`, `"nightly"`, `"beta"`, or a URL to a custom zip. Check the schema for the full list. ### 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 ```json { "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"`