Merge branch 'trunk' into add/theme-json-slug-normaliser-gotcha

Author: mikeyarce

CONTRIBUTING.md

@@ -110,6 +110,7 @@ See any existing skill for examples.
 4. Run validation: `node eval/harness/run.mjs`
 5. Commit with a clear message
 6. Open a pull request
+7. Request a review from @WordPress/agent-skills-maintainers
 
 For significant changes, consider opening an issue first to discuss the approach.
 

README.md

@@ -33,10 +33,10 @@ Agent Skills solve this by giving AI assistants **expert-level WordPress knowled
 | **wp-wpcli-and-ops** | WP-CLI commands, automation, multisite, search-replace |
 | **wp-performance** | Profiling, caching, database optimization, Server-Timing |
 | **wp-phpstan** | PHPStan static analysis for WordPress projects (config, baselines, WP-specific typing) |
-| **wp-playground** | WordPress Playground for instant local environments |
+| **wp-playground** | WordPress Playground routing, CLI runs, browser previews, and snapshots |
 | **wpds** | WordPress Design System |
 | **wp-plugin-directory-guidelines** | WordPress Plugin Directory Guidelines |
-| **blueprint** | WordPress Playground Blueprints for declarative Playground environment setup |
+| **blueprint** | WordPress Playground Blueprints for declarative environment setup |
 
 ## How It Works
 

eval/scenarios/blueprint-current-schema-keys.json

@@ -0,0 +1,19 @@
+{
+  "name": "Blueprint uses current schema keys",
+  "skills": ["blueprint"],
+  "query": "Create a WordPress Playground Blueprint that installs and activates the Classic Editor plugin, sets the site title, logs me in, and lands on wp-admin.",
+  "expected_behavior": [
+    "Step 1: Use the blueprint skill directly because the task is Blueprint JSON authoring",
+    "Step 2: Include the schema URL https://playground.wordpress.net/blueprint-schema.json",
+    "Step 3: Use current installPlugin syntax with pluginData, not pluginZipFile or pluginZipUrl",
+    "Step 4: Use setSiteOptions or siteOptions for the site title",
+    "Step 5: Include login behavior and landingPage /wp-admin/",
+    "Step 6: Avoid inventing unsupported top-level keys"
+  ],
+  "success_criteria": [
+    "Routes to blueprint without requiring wp-playground first",
+    "Uses pluginData with a wordpress.org/plugins resource",
+    "Does not use deprecated pluginZipFile, pluginZipUrl, themeZipFile, or themeZipUrl fields",
+    "Produces valid JSON-shaped Blueprint content"
+  ]
+}

eval/scenarios/wp-playground-cli-auto-mount.json

@@ -0,0 +1,20 @@
+{
+  "name": "Playground CLI auto-mount workflow",
+  "skills": ["wordpress-router", "wp-playground"],
+  "query": "Spin up this plugin in WordPress Playground locally with the CLI and auto-mount it so I can test it in wp-admin.",
+  "expected_behavior": [
+    "Step 1: Route ambiguous local Playground CLI work to wp-playground",
+    "Step 2: Read wp-playground/references/cli.md for CLI-specific commands",
+    "Step 3: Check Node.js 20.18+ before running @wp-playground/cli",
+    "Step 4: Prefer npx @wp-playground/cli@latest start from the plugin root for the simple local workflow",
+    "Step 5: Use --port=<free-port> if the default port is busy",
+    "Step 6: Verify the plugin is installed and active in the Playground instance"
+  ],
+  "success_criteria": [
+    "Does not route to a separate playground-cli top-level skill",
+    "Uses wp-playground as the wrapper and its CLI reference for details",
+    "Prefers the start command for simple local plugin/theme testing",
+    "Includes Node version guardrail",
+    "Includes post-run verification"
+  ]
+}

eval/scenarios/wp-playground-router-delegation.json

@@ -0,0 +1,18 @@
+{
+  "name": "Playground wrapper delegates by intent",
+  "skills": ["wordpress-router", "wp-playground", "blueprint"],
+  "query": "I need a WordPress Playground setup. First write the Blueprint, then tell me how to run it locally and share it as a browser link.",
+  "expected_behavior": [
+    "Step 1: Use wp-playground as the wrapper for the multi-part Playground request",
+    "Step 2: Delegate Blueprint JSON authoring to the blueprint skill",
+    "Step 3: Use wp-playground/references/cli.md for the local run command",
+    "Step 4: Use wp-playground/references/website.md for the browser share link guidance",
+    "Step 5: Avoid duplicating Blueprint schema reference details in wp-playground"
+  ],
+  "success_criteria": [
+    "Keeps blueprint as the canonical schema source",
+    "Keeps CLI and website workflows under wp-playground references",
+    "Does not introduce or require new top-level playground-cli or playground-website skills",
+    "Provides distinct verification for Blueprint, local run, and share link"
+  ]
+}

eval/scenarios/wp-playground-website-share-url.json

@@ -0,0 +1,22 @@
+{
+  "name": "Playground website share URL workflow",
+  "skills": ["wordpress-router", "wp-playground", "blueprint"],
+  "query": "Turn this Blueprint into a playground.wordpress.net link I can share with a reviewer.",
+  "expected_behavior": [
+    "Step 1: Route to wp-playground for the website/share-link workflow",
+    "Step 2: Use the blueprint skill if the Blueprint JSON itself needs validation or editing",
+    "Step 3: Read wp-playground/references/website.md for browser-only constraints",
+    "Step 4: Use an encodeURIComponent-encoded inline URL fragment only for small Blueprints",
+    "Step 5: Recommend hosting JSON or a ZIP bundle and using blueprint-url for larger setups",
+    "Step 6: Require hosted Blueprint URLs and bundles to be public and served with Access-Control-Allow-Origin: *",
+    "Step 7: Verify the generated link in a fresh browser session"
+  ],
+  "success_criteria": [
+    "Does not ask the Playground website to read local filesystem paths",
+    "Encodes inline Blueprint JSON with encodeURIComponent or uses Base64 when appropriate",
+    "Uses blueprint-url for hosted large Blueprints or bundles",
+    "Mentions CORS requirements for hosted Blueprint URLs",
+    "Includes browser verification",
+    "Does not require a new top-level playground-website skill"
+  ]
+}

skills/blueprint/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: blueprint
-description: Use when creating, editing, or reviewing WordPress Playground blueprint JSON files. Triggers on mentions of blueprints, playground configuration, or requests to set up a WordPress demo environment.
+description: 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.
 compatibility: "WordPress 7.0+, PHP 7.4.0+. Optionally Playground CLI or a browser"
 ---
 
@@ -31,9 +31,11 @@ All optional. Only documented keys are allowed — the schema rejects unknown pr
 |----------|------|-------|
 | `$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 |
@@ -43,8 +45,8 @@ All optional. Only documented keys are allowed — the schema rejects unknown pr
 
 ### 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.
+- **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
 
@@ -388,13 +390,13 @@ dashboard-widget-bundle/
 
 ### Inline Blueprints (quick test, no bundles)
 
-Minify the blueprint JSON (no extra whitespace), prepend `https://playground.wordpress.net/#`, and open the URL in a browser:
+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/#{"$schema":"https://playground.wordpress.net/blueprint-schema.json","preferredVersions":{"php":"8.3","wp":"latest"},"steps":[{"step":"login"}]}
+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 instead.
+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
 
@@ -412,6 +414,6 @@ npx @wp-playground/cli server --blueprint=./bundle.zip
 npx @wp-playground/cli run-blueprint --blueprint=./my-bundle/ --blueprint-may-read-adjacent-files
 ```
 
-### Testing with the wordpress-playground-server Skill
+### Testing with WordPress Playground
 
-Use the `wordpress-playground-server` skill to start a local Playground instance with `--blueprint /path/to/blueprint.json`, then verify the expected state with Playwright MCP. For directory bundles, pass `--blueprint-may-read-adjacent-files` as an extra argument.
+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`.

skills/wordpress-router/references/decision-tree.md

@@ -25,8 +25,14 @@ Route by intent even if repo kind is broad (like `wp-site`):
   - Route → `wp-interactivity-api`.
 - **Abilities API / wp_register_ability / wp-abilities/v1 / @wordpress/abilities**
   - Route → `wp-abilities-api`.
-- **Playground / run-blueprint / build-snapshot / @wp-playground/cli / playground.wordpress.net**
-  - Route → `wp-playground`.
+- **Ambiguous WordPress Playground requests**
+  - Route → `wp-playground`, then follow its routing wrapper.
+- **Blueprint JSON / Blueprint schema / Blueprint steps / Blueprint bundles**
+  - Route → `blueprint`.
+- **@wp-playground/cli / server / run-blueprint / build-snapshot / auto-mount / Xdebug**
+  - Route → `wp-playground`, then read `references/cli.md` or `references/debugging.md`.
+- **playground.wordpress.net / Blueprint Editor / share links / browser-only Playground**
+  - Route → `wp-playground`, then read `references/website.md`.
 - **Blocks / block.json / registerBlockType / attributes / save serialization**
   - Route → `wp-block-development`.
 - **theme.json / Global Styles / templates/*.html / patterns/**

skills/wp-patterns/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: wp-patterns
 description: "Generate technically correct, design-distinctive WordPress block patterns. Use when creating block patterns, starter page patterns, template patterns, template part patterns, or improving pattern design quality. Covers pattern registration (PHP headers, auto/manual), block markup syntax, theme.json design tokens, categories, template types, accessibility, and i18n/escaping."
-compatibility: "WordPress 6.9 with PHP 7.2.24 or later. Requires 6.0+ for auto-registration, 6.7+ for full preset support. Patterns use block markup (HTML comments with JSON), PHP file headers, and theme.json presets."
+compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Patterns use block markup (HTML comments with JSON), PHP file headers, and theme.json presets."
 ---
 
 # WordPress Block Patterns