[wp-playground] Split into routing wrapper with cli + website references

[bgrgicak]

Summary

Refactors the wp-playground skill into a thin routing wrapper and splits its prior procedure into focused references (cli.md, website.md), clarifies the ownership boundary with the blueprint skill, and adds eval scenarios that cover the new routing.

Motivation for the change, related issues

The previous wp-playground SKILL.md mixed CLI commands, browser/share-link tips, and Blueprint guidance into a single procedure, which:

• duplicated Blueprint schema details that already live in the blueprint skill,
• buried the browser-only playground.wordpress.net surface area (Query API, window.playgroundSites, active PlaygroundClient) under a single bullet,
• left the router unable to delegate "Blueprint JSON" vs. "run/share a Playground" cleanly.

This PR makes the split explicit so each skill owns one concern and the router can route by intent.

Implementation details

wp-playground becomes a routing wrapper

• skills/wp-playground/SKILL.md is rewritten as a short router: pick Blueprint vs. CLI vs. website vs. debugging, then load the matching reference.
• Description is sharpened to say it covers ambiguous Playground work, CLI runs, share links, browser previews, snapshots, mounts, version switching, and Xdebug, and to defer Blueprint JSON authoring to the blueprint skill.

Focused references under wp-playground

• New skills/wp-playground/references/cli.md covers @wp-playground/cli workflows: start for the common local plugin/theme dev loop, server for advanced/CI use, manual --mount, run-blueprint, build-snapshot, version switching, verification, and failure modes.
• New skills/wp-playground/references/website.md covers playground.wordpress.net: URL setup (Query API + Blueprint URLs/fragments), the window.playgroundSites site-manager, and the active window.playground PlaygroundClient. Includes CORS, persistence, and browser-only constraints.
• skills/wp-playground/references/debugging.md is updated to match current CLI flags (--xdebug, --debug, --workers=<n|auto>) and drops stale references like --experimental-multi-worker.
• Old references/blueprints.md and references/cli-commands.md are removed since their content now lives in blueprint and the new cli.md respectively.

blueprint skill claims schema ownership

• skills/blueprint/SKILL.md description now explicitly owns Blueprint JSON authoring, validation, and review, and points purely-runtime requests to wp-playground.
• Documents the deprecated top-level description and phpExtensionBundles keys, and corrects the supported preferredVersions.php enumeration plus wp: false semantics.
• Inline-Blueprint URL example now uses encodeURIComponent() so it does not silently break for JSON with reserved characters, and points to wp-playground/references/website.md for share-link guidance.

Router updates

• skills/wordpress-router/references/decision-tree.md replaces the single Playground line with intent-based rules: ambiguous Playground → wp-playground; Blueprint JSON/schema/steps/bundles → blueprint; CLI flows → wp-playground + cli.md; website/share links → wp-playground + website.md.

Eval scenarios

Adds four scenarios that exercise the new boundaries:

• eval/scenarios/wp-playground-cli-auto-mount.json — local CLI auto-mount workflow goes through wp-playground + cli.md.
• eval/scenarios/wp-playground-website-share-url.json — share-link workflow goes through wp-playground + website.md, with CORS + encoding rules.
• eval/scenarios/wp-playground-router-delegation.json — multi-part request delegates JSON to blueprint and runtime/share to wp-playground.
• eval/scenarios/blueprint-current-schema-keys.json — Blueprint JSON authoring routes directly to blueprint and avoids deprecated keys.

Out of scope

• No new top-level playground-cli or playground-website skills; both stay as wp-playground references.
• No changes to the Playground CLI itself or to playground.wordpress.net.

Testing Instructions

1. Read skills/wp-playground/SKILL.md and confirm it routes by intent without restating Blueprint schema or full CLI procedures.

2. Open skills/wp-playground/references/cli.md and skills/wp-playground/references/website.md and confirm each covers a single concern (local CLI vs. browser website).

3. Open skills/blueprint/SKILL.md and confirm Blueprint JSON authoring (schema keys, deprecated fields, inline-URL encoding) lives there and no longer in wp-playground.

4. Open skills/wordpress-router/references/decision-tree.md and walk through the four Playground-related bullets to confirm intent-based routing.

5. Review the four new scenarios under eval/scenarios/ and confirm expected_behavior and success_criteria match the new skill boundaries.

6. Optional sanity check — run a real local Playground command from the new reference, e.g.:

   cd <plugin-or-theme-root>
   npx @wp-playground/cli@latest start

   and confirm the plugin/theme is auto-mounted and active in wp-admin.

🤖 Generated with Claude Code

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: bgrgicak <berislavgrgicak@git.wordpress.org>
Co-authored-by: mikeyarce <mikeyarce@git.wordpress.org>
Co-authored-by: fellyph <fellyph@git.wordpress.org>
Co-authored-by: jonathanbossenger <psykro@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[fellyph]

LGTM, Thanks @bgrgicak

[bgrgicak]

Installing plugins from URL should be explained in the skill

[bgrgicak]

@jonathanbossenger, when you get a chance, could you please take a look at this PR?

[jonathanbossenger]

@bgrgicak, thank you for your pull request to improve WordPress agent-skills.

I used AI to review this PR, and it suggested these changes. Let me know what you think.

• The new wp-playground SKILL.md is missing a Procedure section. The skill now acts as a routing wrapper, which is a great architectural choice, but the "Route by intent" bullet list functions as an implicit procedure without being labeled as one. Other skills in the repo (wp-block-development, blueprint) use explicit "## Procedure" headings with numbered steps. Consider renaming "Route by intent" to "## Procedure" or adding a brief procedure that says: (1) identify user intent, (2) route to the correct reference or skill per the table below. This would align with the six-section convention and make the skill scannable for agents.
• The new wp-playground SKILL.md is missing a Failure modes section. The old SKILL.md had explicit failure modes (port conflicts, mount issues, Node version errors). These are now in references/cli.md, which is good for depth, but the wrapper SKILL.md should at least mention common routing failures — e.g., "user asks for Blueprint help but gets routed to wp-playground instead of blueprint" or "user needs local filesystem access but gets sent to website.md". A brief top-level Failure modes section helps the agent self-correct routing mistakes.
• The debugging reference is linked as "references/debugging.md" in the SKILL.md routing list, but the SKILL.md says "read references/debugging.md after references/cli.md". This creates a soft 2-hop pattern: the agent must load cli.md first, then debugging.md. Per the 1-hop rule, SKILL.md should link to both directly and independently. Consider rewording to "read references/debugging.md for Xdebug and stuck CLI runs" without the "after cli.md" dependency, or consolidate the debugging content into cli.md since it is only about 20 lines.
• The blueprint SKILL.md description change is good — it now disambiguates from wp-playground with "For only running or sharing a Playground environment, use wp-playground." However, the wp-playground description says "For Blueprint JSON authoring or review, prefer the blueprint skill directly." The word "prefer" is softer than "use" — agents may still route Blueprint work to wp-playground. Consider strengthening to "use the blueprint skill directly" (matching the blueprint skill's phrasing) for consistent disambiguation.
• [Must-fix — verify] The four new eval scenarios are excellent and well-structured. However, the scenario "wp-playground-cli-auto-mount.json" references skills: ["wordpress-router", "wp-playground"], and "wp-playground-router-delegation.json" references skills: ["wordpress-router", "wp-playground", "blueprint"]. Verify that the eval harness resolves these multi-skill references correctly — the scenarios test cross-skill routing, which is the right thing to test, but confirm the harness supports this pattern.

Other nitpick items:

• In the blueprint SKILL.md diff, the new row for "phpExtensionBundles" uses type "any" with description "Deprecated/no longer used; omit in new Blueprints". Consider using type "array" (its original type) rather than "any" for schema accuracy, even though it is deprecated.
• The website.md reference (11KB) is comprehensive but quite long. Consider whether the "Manage browser sites" and "Interact with the active WordPress site" sections could be split into a separate reference if the file grows further. For now it is fine.
• Minor inconsistency: the README.md updates the blueprint description to "WordPress Playground Blueprints for declarative environment setup" (dropping "Playground" from the longer phrase), but the blueprint SKILL.md title is still "# Blueprint". These are fine independently but worth noting.

[bgrgicak]

Thanks for the feedback @jonathanbossenger, I addressed it in Refine Playground skill routing guidance.

[jonathanbossenger]

Thanks @bgrgicak

I used AI to re-review the latest update, and it suggested one remaining change. I verified this using a different model/harness.

• Remove the remaining reference-to-reference routing in skills/wp-playground/references/cli.md (which sends the agent to references/debugging.md) and skills/wp-playground/references/website.md (which sends the agent to references/cli.md). The wrapper now links all three references directly, so these handoffs can instead tell the agent to return to the wp-playground routing procedure. This preserves the repo's 1-hop rule and avoids loading one reference to discover another.

[bgrgicak]

Thanks @jonathanbossenger! I addressed your feedback in 0da2e4b

[mikeyarce]

Looks great, thanks @bgrgicak !

[bgrgicak]

@fellyph the updated Playground skills are biw merged in case you want to announce them.

[fellyph]

@bgrgicak I have drafted it. I will send you the preview.