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
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.
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.
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.
|
2 participants
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.