Skip to content

Add wp-env skill for local WordPress development - #38

Merged
bgrgicak merged 2 commits into
WordPress:trunkfrom
rushikeshmore:add/wp-env-skill
Sep 21, 2026
Merged

bgrgicak merged 2 commits into
WordPress:trunkfrom
rushikeshmore:add/wp-env-skill

Conversation

@rushikeshmore

Copy link
Copy Markdown
Contributor

What?

Adds a new wp-env skill 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/env is 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

  • All 7 required sections (When to use, Inputs required, Procedure, Verification, Failure modes, Escalation)
  • Covers: installation, auto-detection (plugin/theme/core), .wp-env.json configuration, source string formats, WP-CLI commands, PHPUnit testing, Xdebug setup, multisite, override files, environment management
  • Common gotchas table (port conflicts, bare slugs, override merge behavior, Docker not running)

Eval scenarios: 2 JSON scenarios

  • wp-env-start-plugin.json -- setting up wp-env for a plugin project
  • wp-env-troubleshoot-port.json -- diagnosing and fixing port conflicts

README: Updated Available Skills table with wp-env entry.

Testing

  • node eval/harness/run.mjs passes
  • node shared/scripts/skillpack-build.mjs --clean builds successfully for all 4 targets (codex, vscode, claude, cursor)
  • Skill follows required SKILL.md structure with all 7 sections
  • Two eval scenarios added
  • Frontmatter validates (name matches folder, compatibility includes WP 6.9 + PHP 7.2.24+)

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.

@github-actions

github-actions Bot commented Apr 9, 2026 •

Copy link
Copy Markdown
Contributor

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: rushikeshmore <rushikeshmore@git.wordpress.org>
Co-authored-by: mikeyarce <mikeyarce@git.wordpress.org>
Co-authored-by: bgrgicak <berislavgrgicak@git.wordpress.org>

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

@rushikeshmore

Copy link
Copy Markdown
Contributor Author

Hi, just checking if this is ready for review or if anything needs changing on my end. Happy to adjust.

@mikeyarce mikeyarce left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread skills/wp-env/SKILL.md Outdated
---
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+.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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+."

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread skills/wp-env/SKILL.md Outdated
@@ -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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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."

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied.

Comment thread skills/wp-env/SKILL.md Outdated
| 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) |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd probably drop the sudo reccommendation here

Suggested change
| 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` |

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied. Agreed, recommending sudo for an npm global install is bad advice to leave in a skill an agent will follow.

Comment thread skills/wp-env/SKILL.md
- 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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- 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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@rushikeshmore

Copy link
Copy Markdown
Contributor Author

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.

node eval/harness/run.mjs passes.

@mikeyarce mikeyarce left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@mikeyarce
mikeyarce requested a review from bgrgicak August 5, 2026 15:04
Comment thread skills/wp-env/SKILL.md
- 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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, left this section as is.

@bgrgicak

Copy link
Copy Markdown
Contributor

@mikeyarce sorry for the late reply, I was afk for a while.

Preferring wp-env over Playground for development makes sense.
The routing for when to choose wp-env seems good.

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.
@rushikeshmore

Copy link
Copy Markdown
Contributor Author

Thanks @bgrgicak, good catch. Added a short paragraph under the routing block (ad1082d) that names the Playground runtime explicitly: --runtime=playground is still wp-env driven by the same .wp-env.json, so it is a Docker-free fallback for projects that already carry wp-env config, not a third option. It also spells out what that runtime gives up (SQLite instead of MySQL, no wp-env run, no separate tests environment) based on the make/playground post, and points to the wp-playground skill for a quick Docker-free WordPress with no wp-env config.

Left the "When to use" bullet unchanged per your inline note. Rebased on trunk, harness passes.

@bgrgicak bgrgicak left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bgrgicak
bgrgicak merged commit ac16175 into WordPress:trunk Sep 21, 2026
5 checks passed
henryperkins added a commit to henryperkins/agent-skills that referenced this pull request Sep 27, 2026
… 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>
henryperkins added a commit to henryperkins/agent-skills that referenced this pull request Sep 27, 2026
…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>
henryperkins added a commit to henryperkins/agent-skills that referenced this pull request Sep 27, 2026
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants