WordPress Playground is not a single interface. A developer may use the Playground CLICLI Command Line Interface. Terminal (Bash) in Mac, Command Prompt in Windows, or WP-CLI for WordPress. for local work, a Blueprint to describe a reproducible site, or playground.wordpress.net to create and share a browser-based demo. An AI agent needs to know which surface owns each part of a request.
PR #56 in the WordPress agent-skills repository updates the wp-playground skill around that idea. Instead of keeping CLI commands, Blueprint advice, browser links, and debugging notes in one long procedure, the skill becomes a small routing layer with focused references.
The result gives agents a clearer model of the whole Playground ecosystem. In this post, we are going to cover the main updates on the WordPress Playground agent skill, which is present in the WordPress repository. If you want an introduction post, I do recommend reading the previous post about the Playground agent skill.
What changes for Playground users
- A developer starting a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party. locally gets the current
startworkflow and a check that the plugin is active. - A reviewer receiving a demo link gets correct encoding, public hosting and CORS requirements, and a fresh-browser verification step.
- A mixed request can move from Blueprint authoring to local execution and browser sharing without one skill pretending to own every concern.
The headline benefit is consistency across surfaces: the answer changes with the workflow, while the underlying model of Playground stays coherent.
Why the previous skill reached its limit
The previous 101-line SKILL.md put local execution, Blueprint guidance, browser sharing, and debugging in one procedure. That created three failure modes:
- Browser support was too shallow to explain the Query API, persistence, or the difference between
window.playgroundSitesand the activewindow.playgroundclient. - Blueprint guidance existed in both
wp-playgroundand the dedicatedblueprintskill, creating two sources of truth. - The common plugin and theme workflow still led with
server --auto-mountafter the Playground CLI documentation had moved the typical development loopLoop The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. https://codex.wordpress.org/The_Loop tostart.
The current high-level workflow is:
cd <plugin-or-theme-root>
node -v
npx @wp-playground/cli@latest startThe server command remains useful when an agent needs explicit mounts, a disposable environment, CI behavior, or fine-grained runtime control. The important change is teaching the agent to choose, not treating one command as the answer to every local workflow.
Route by intent, then load the detail
The new wp-playground wrapper starts by classifying the request:
| Request type | Owner | Expected outcome |
|---|---|---|
| Write or review Blueprint JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. | blueprint skill | Current schema, supported steps, and valid resources |
| Run a plugin, theme, or Blueprint locally | wp-playground → CLI reference | Appropriate command, mount strategy, and verification |
| Debug Xdebug or a stuck CLI run | wp-playground → debugging reference | Relevant logs, flags, and worker guidance |
| Create a browser link or automate a browser site | wp-playground → website reference | Correct URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org or APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. surface with browser constraints |
| Combine authoring, local execution, and sharing | Wrapper composes the routes | One staged workflow with clear ownership |
Mixed requests can use more than one route. For example, “write a Blueprint, run it locally, and give me a reviewer link” uses blueprint for the JSON, the CLI reference for local execution, and the website reference for sharing.
This is progressive disclosure in practice. The entry file drops from 101 to 52 lines. The complete bundle grows because it documents more capability, but an agent loads that depth only when the request needs it.
Browser sharing becomes a first-class route
The website reference distinguishes three control surfaces:
- URL setup through Query API parameters, Blueprint fragments, and
blueprint-url. - Browser site management through the Sites API at
window.playgroundSites. - Runtime interaction through the JavaScript API client exposed as
window.playground.
That distinction prevents several common mistakes. playgroundSites manages site records, persistence, and the active site. The Playground client reads and writes the WordPress virtual filesystem, runs PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/index.php, makes requests, and navigates the visible site. URL parameters configure a site before it boots.
The reference also documents boundaries that matter when an agent generates a share link:
- Small inline Blueprints should be encoded once with
encodeURIComponent(JSON.stringify(blueprint)). - Larger JSON files and ZIP bundles should use
?blueprint-url=<public-url>. - Hosted files must be public and allow cross-origin loading.
- A browser Playground cannot read an arbitrary local filesystem path.
- The final URL should be checked in a fresh browser session.
These details turn “make a Playground link” from a plausible-looking string into a repeatable handoff. The official troubleshooting guide confirms that raw JSON in a fragment, double encoding, private URLs, and missing CORS headers are frequent failure modes.
At the same time, the blueprint skill now explicitly owns Blueprint JSON and bundles, and the debugging reference replaces stale worker advice with current flags. The router can therefore choose a source before the agent starts composing an answer.
What the benchmark showed
To measure the impact, I compared three configurations:
- The new version.
- The previous skill.
- A control that answered from general model knowledge without consulting a skill.
The benchmark used the four scenarios added by the PR: CLI auto-mounting, website sharing, a mixed Blueprint/CLI/browser request, and current Blueprint schema authoring. Every configuration received the same prompts running on GPT 5.5 Sol. The two skill configurations could read only the files from their pinned revision, while the control could not read skill files or references.
On this four-scenario, 24-assertion regression suite:
| Scenario | New skill | Previous skill | Without skill |
|---|---|---|---|
| CLI auto-mount | 5/5 (100%) | 4/5 (80%) | 1/5 (20%) |
| Website share URL | 6/6 (100%) | 5/6 (83.3%) | 2/6 (33.3%) |
| Mixed Blueprint, CLI, and website workflow | 6/6 (100%) | 6/6 (100%) | 3/6 (50%) |
| Current Blueprint schema | 7/7 (100%) | 7/7 (100%) | 6/7 (85.7%) |
| All assertions | 24/24 (100%) | 22/24 (91.7%) | 12/24 (50%) |
Six criteria inspect the execution trace rather than the final answer. Five explicitly require the agent to use or route through a skill, so they necessarily penalize the no-skill control. Removing all six produces a cleaner comparison of answer content:
| Answer-content score | New skill | Previous skill | Without skill |
|---|---|---|---|
| Passed criteria | 18/18 (100%) | 16/18 (88.9%) | 11/18 (61.1%) |
The final PR revision passed 24/24 checks: 100% on this four-scenario, 24-assertion regression suite. Only two content checks separated it from the previous skill:
- It chose
npx @wp-playground/cli@latest startfor the common plugin-development workflow. - It required public, CORS-enabled hosting with
Access-Control-Allow-Origin: *for Blueprint files, bundles, and referenced assets.
The Blueprint-only scenario did not distinguish answer quality; all three configurations passed its six content checks. That is evidence of preserved behavior, not improvement.
This is a focused regression suite, not a general model leaderboard. It uses one run per prompt, does not measure run-to-run variance, and grades guidance rather than live Playground execution.
Review improved the architecture
The pull request’s review history also shaped the final structure. Review feedback asked for an explicit routing procedure, top-level failure modes, stronger delegation to blueprint, and direct one-hop links from the wrapper to each reference.
The final revision removes reference-to-reference handoffs. A CLI or website reference now sends the agent back to the wrapper when the request changes direction. That keeps every focused file one hop from SKILL.md and makes the routing model easier to inspect.
Consistency across surfaces
The improvement is not merely a higher benchmark score. It is a more consistent developer experience across the CLI, Blueprints, and browser sharing. A request can move from a valid Blueprint to a local run and then to a reviewer link while each skill remains responsible for one concern.
PR #56 was merged on July 25, 2026. You can inspect the complete change set and use the four scenarios as starting points for testing real Playground tasks.