Repository navigation
Add wp-env skill for local WordPress development - #38
Conversation
|
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 If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
|
Hi, just checking if this is ready for review or if anything needs changing on my end. Happy to adjust. |
mikeyarce
left a comment
There was a problem hiding this comment.
Thanks for the contribution @rushikeshmore !
Added a few notes that I think we need to work on before this is ready.
I think one of my concerns is having multiple "dev envs" like wp-env and playground, so I suggested adding some wording to help the agent know which to use when.
Once this is merged I'll make a follow-up PR with some similar instructions on the wp-playground side.
| --- | ||
| name: wp-env | ||
| description: Use when setting up, configuring, or troubleshooting local WordPress development environments with @wordpress/env (wp-env). Triggers on mentions of wp-env, local WordPress development, Docker-based WordPress, or requests to start/stop/configure a local WordPress instance. | ||
| compatibility: Targets WordPress 6.9+ (PHP 7.2.24+). Requires Docker and Node.js 18.12+. |
There was a problem hiding this comment.
| compatibility: Targets WordPress 6.9+ (PHP 7.2.24+). Requires Docker and Node.js 18.12+. | |
| compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Requires Docker and Node.js 18.12+." |
There was a problem hiding this comment.
Applied. Worth noting this was more than style: the harness now requires "WordPress 7.0" and "PHP 7.4.0" in compatibility after #70, so the old 6.9 / 7.2.24 string fails validation on current trunk.
| @@ -0,0 +1,212 @@ | |||
| --- | |||
| name: wp-env | |||
| description: Use when setting up, configuring, or troubleshooting local WordPress development environments with @wordpress/env (wp-env). Triggers on mentions of wp-env, local WordPress development, Docker-based WordPress, or requests to start/stop/configure a local WordPress instance. | |||
There was a problem hiding this comment.
| description: Use when setting up, configuring, or troubleshooting local WordPress development environments with @wordpress/env (wp-env). Triggers on mentions of wp-env, local WordPress development, Docker-based WordPress, or requests to start/stop/configure a local WordPress instance. | |
| description: "Use when setting up, configuring, or troubleshooting local WordPress development environments with @wordpress/env (wp-env). Triggers on mentions of wp-env, local WordPress development, Docker-based WordPress, or requests to start/stop/configure a local WordPress instance." |
| | Override not taking effect | Wrong merge behavior | `plugins`/`themes` in override **replace** base arrays; only `config`/`mappings` merge | | ||
| | Tests environment not accessible | Wrong port | Test environment runs on port 8889 by default | | ||
| | Xdebug not connecting | IDE not listening or wrong port | Ensure IDE listens on port 9003 with correct `pathMappings` | | ||
| | npm global install permission error | Node installed without nvm | Use `nvm` or prefix with `sudo` (not recommended) | |
There was a problem hiding this comment.
I'd probably drop the sudo reccommendation here
| | npm global install permission error | Node installed without nvm | Use `nvm` or prefix with `sudo` (not recommended) | | |
| | npm global install permission error | Node installed to a system path | Use `nvm`, or install locally: `npm i -D @wordpress/env` and run via `npx wp-env` | |
There was a problem hiding this comment.
Applied. Agreed, recommending sudo for an npm global install is bad advice to leave in a skill an agent will follow.
| - Project contains a `.wp-env.json` file | ||
| - User mentions `wp-env`, `@wordpress/env`, or Docker-based WordPress development | ||
| - User wants to run WP-CLI commands, PHPUnit tests, or debug with Xdebug locally | ||
| - Triage detects a plugin or theme project that needs a local WordPress instance |
There was a problem hiding this comment.
| - Triage detects a plugin or theme project that needs a local WordPress instance | |
| - Triage detects a plugin or theme project that needs a local WordPress instance | |
| **wp-env or wp-playground?** For a quick local WordPress, prefer the **wp-playground** skill by default — it's faster, disposable, and needs no Docker. Use **wp-env** when the task actually requires it: | |
| - the repo already contains a `.wp-env.json` | |
| - a real MySQL database is needed (PHPUnit against the DB, `wp db` commands, data that survives restarts) | |
| - arbitrary commands must run inside the environment (shell access, Composer, full WP-CLI via `wp-env run`) | |
| - this is a WordPress core or Gutenberg checkout | |
| - the user explicitly asks for wp-env or Docker |
There was a problem hiding this comment.
Applied as written.
One knock-on effect: the plugin eval scenario asked "set up a local WordPress development environment for my plugin so I can test it", which under this new guidance should route to wp-playground, not wp-env. I updated that scenario so it does not contradict the skill: the query now asks for PHPUnit against a real database, and choosing wp-env over wp-playground is an explicit step plus a success criterion. Happy to revert that part if you would rather keep the scenarios untouched.
Agreed on the follow-up for the wp-playground side.
1d0087e to
e298706
Compare
|
Thanks for the review. All four suggestions applied, and the branch is rebased on trunk so the conflict is gone.
One extra change beyond the suggestions: the plugin eval scenario used a generic "set up a local environment" query that the new routing block would send to wp-playground. I made it a real wp-env case (PHPUnit against a database) and added the routing decision as a step. Details in the thread, easy to revert if you want the scenarios left alone.
|
mikeyarce
left a comment
There was a problem hiding this comment.
Thanks @rushikeshmore !
@bgrgicak can you take a look? I know you worked on the Playground skills and would like to have your opinion here. Specifically, do you think the routing will be good here? I think we should only use wp-env when people ask directly or when it's needed for things like PHPUnit etc.
| - User asks to set up a local WordPress development environment | ||
| - Project contains a `.wp-env.json` file | ||
| - User mentions `wp-env`, `@wordpress/env`, or Docker-based WordPress development | ||
| - User wants to run WP-CLI commands, PHPUnit tests, or debug with Xdebug locally |
There was a problem hiding this comment.
I'm not sure if it matters, Playground CLI can run WP-CLI, PHPUnit and Xdebug, so there aren't blockers.
I would leave this section as is.
There was a problem hiding this comment.
Agreed, left this section as is.
|
@mikeyarce sorry for the late reply, I was afk for a while. Preferring wp-env over Playground for development makes sense. There's just one thing I would clarify. WP-env supports Playground as a runtime. This could be confusing to the agent if we don't clarify what to use and when. |
Add a new skill teaching AI assistants how to set up, configure, and troubleshoot @wordpress/env local development environments. Covers: installation, auto-detection, .wp-env.json configuration, WP-CLI commands, PHPUnit testing, Xdebug, multisite, port conflicts, and common failure modes. Includes two eval scenarios: - wp-env-start-plugin: setting up wp-env for plugin development - wp-env-troubleshoot-port: diagnosing and fixing port conflicts Addresses community request in WordPress#9.
wp-env can run on Playground instead of Docker, which blurs the line between this skill and wp-playground. Spell out that the runtime flag is still wp-env driven by the same config, what it gives up, and when to go to the wp-playground skill instead.
e298706 to
ad1082d
Compare
|
Thanks @bgrgicak, good catch. Added a short paragraph under the routing block (ad1082d) that names the Playground runtime explicitly: Left the "When to use" bullet unchanged per your inline note. Rebased on trunk, harness passes. |
… security Merges the six commits WordPress/agent-skills trunk was ahead by: - ac16175 Add wp-env skill for local WordPress development (WordPress#38) - ad58e37 Add plugin security guidance for escaping and AJAX (WordPress#63) - f2f6af2 Fix Plugin/Theme header detection in PHP docblocks (WordPress#103) - e9c58d5 Adding reference to webMCP at Playground Skill (WordPress#105) - 9f4a603 chore: refresh upstream indices (WordPress#92) - f1bac1f Add repository-wide CODEOWNERS for agent-skills maintainers (WordPress#108) Conflict resolutions: shared/references/wordpress-core-versions.json Kept ours. api.wordpress.org/core/version-check/1.7 reports 7.1.2 (checked 2026-09-27); upstream's WordPress#92 snapshot stops at 7.1.1. The Gutenberg index merged cleanly: both sides already carry v24.0.0, and v24.1.0 is still at rc.1. skills/wp-project-triage/scripts/detect_wp_project.mjs Kept ours. The fork already fixed WordPress#103's bug with `^[\s*#]*`, which matches every header line upstream's `^\s*\*?\s*` does, plus `#`-led lines. The detect_plugins.mjs half of WordPress#103 merged cleanly; the fork had not fixed that file. Both detectors now report docblock, bare, and non-plugin fixtures correctly. skills/wp-playground/SKILL.md Kept the fork's frontmatter (Use-when opener, 6.9 floor, GPL license) and folded WordPress#105's "WebMCP site tools" into the description. Took WordPress#105's browser-workflow routing bullet in the fork's markdown-link style; it also drops the "Blueprint Editor" claim, which website.md never covered. Clean merges: website.md now routes existing-site work to the new webmcp.md, mcp.md, and sites-api.md references (the WebMCP tool names match packages/playground/mcp in WordPress/wordpress-playground); security.md gains escaping contexts and AJAX handler rules. wp-env arrives exactly as upstream wrote it and is conformed and corrected in the next commit. CODEOWNERS names @WordPress/agent-skills-maintainers, which does not resolve in this fork; kept for tree parity with upstream. The harness is not expected to pass at this commit: wp-env is not yet in the skill inventory and skills/ changed without a version bump. The follow-up commits close both. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…16.0 and route to it Upstream's wp-env skill (WordPress#38) follows the @wordpress/env README, which lags the package code in several places. Checked against the 11.16.0 tarball (published 2026-09-23) and, where behavior mattered, run: - `composer` is not a `wp-env run` container. The package removed it (and `phpunit`), and validate-run-container.js throws on both. The list is now mysql, wordpress, cli, phpmyadmin (only when enabled), plus the tests-* containers. - `wp-env run cli "wp rewrite structure /%postname%/"` fails. run() hands argv to `docker compose exec` with no shell, so the quoted string is looked up as one executable name ("executable file not found in $PATH", reproduced with docker exec). The command is now unquoted, with a short explanation. - `wp-env run mysql mysql ...` fails: the database service is mariadb:lts (12.3.3 today), which ships `mariadb` and no `mysql`. - `npx wp-env` resolves the unscoped `wp-env` npm package when the local install is missing (a third-party "Security PoC" package), and npm assumes --yes in a non-interactive shell. Replaced with the README's own `npm exec --no -- wp-env`. - `cleanup` and `destroy` block on a confirmation prompt unless `--force`; the skill now says to get the user's go-ahead and pass it. - Override files merge `config`, `mappings`, and `lifecycleScripts` (merge-configs.js), not only the first two. - The invalid-source error is `Invalid or unrecognized source: "<value>"`, and a relative path without a leading `.` is parsed as a GitHub repo. - The tests environment still starts by default on 8889 but is deprecated with a startup warning; the skill names the `"testsEnvironment": false` opt-out and the `--config` replacement. - `--auto-port` is ignored when CI is set. Fork conventions: the 6.9 floor per docs/compatibility-policy.md (wp-env covers no 7.0-only API), the license field, a wp-playground boundary in the description, and "verified against @wordpress/env 11.16.0" in prose. @wordpress/env is not a drift-registry upstream, so it carries no `verified through:` marker. Registration: docs/skill-set-v1.md lists 22 skills. The router sends wp-env / .wp-env.json requests to wp-env (upstream still routes wp-env to the planned wp-testing skill) and WordPress#105's WebMCP / Playground MCP terms to wp-playground's website.md. wp-playground's escalation now names the wp-env skill. assertWpEnvPrecision pins the corrections and the fork-only router entry. It fails on upstream's original SKILL.md, and each of its six exclusions matches a line in that original. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Ships the upstream merge and the corrections that followed it: the new wp-env skill (upstream WordPress#38), checked against @wordpress/env 11.16.0 and routed from wordpress-router; WebMCP, Playground MCP, and Sites API routing for wp-playground (WordPress#105); plugin escaping and AJAX guidance (WordPress#63); and the docblock plugin-header fix in detect_plugins.mjs (WordPress#103). The release-conformance gate requires a bump whenever skills/ changes after the last version change, and nine skill files changed since 1.11.0. A new skill makes this a minor release. The manifests now list wp-env. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
What?
Adds a new
wp-envskill that teaches AI coding assistants how to set up, configure, and troubleshoot local WordPress development environments using@wordpress/env.Addresses the community request in #9 (comment from @owlot: "Would love to see an wp-env skill").
Why?
@wordpress/envis the official Docker-based local development tool for WordPress plugin and theme development. It's referenced throughout the Gutenberg docs and used by core contributors, but there's no agent skill covering it. AI assistants currently guess at wp-env configuration and often make mistakes like using bare plugin slugs instead of ZIP URLs, or not checking Docker status before starting.How?
New skill:
skills/wp-env/SKILL.md.wp-env.jsonconfiguration, source string formats, WP-CLI commands, PHPUnit testing, Xdebug setup, multisite, override files, environment managementEval scenarios: 2 JSON scenarios
wp-env-start-plugin.json-- setting up wp-env for a plugin projectwp-env-troubleshoot-port.json-- diagnosing and fixing port conflictsREADME: Updated Available Skills table with wp-env entry.
Testing
node eval/harness/run.mjspassesnode shared/scripts/skillpack-build.mjs --cleanbuilds successfully for all 4 targets (codex, vscode, claude, cursor)Use of AI Tools
Claude Code was used to assist with drafting this skill. Content was verified against the official @wordpress/env documentation and source code.