Bero
977b40746e
## 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.: ```bash 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](https://claude.com/claude-code) --------- Co-authored-by: Mikey Arce <mikeyarce@gmail.com>
8.3 KiB
Agent Skills for WordPress
Teach AI coding assistants how to build WordPress the right way.
Agent Skills are portable bundles of instructions, checklists, and scripts that help AI assistants (Claude, Copilot, Codex, Cursor, etc.) understand WordPress development patterns, avoid common mistakes, and follow best practices.
AI Authorship Disclosure: These skills were generated using GPT-5.2 Codex (High Reasoning) from official Gutenberg and WordPress documentation, then reviewed and edited by WordPress contributors. We tested skills with AI assistants and iterated based on results. This is v1, and skills will improve as the community uses them and contributes fixes. See docs/ai-authorship.md for details. (WordPress AI Guidelines)
Why Agent Skills?
AI coding assistants are powerful, but they often:
- Generate outdated WordPress patterns (pre-Gutenberg, pre-block themes)
- Miss critical security considerations in plugin development
- Skip proper block deprecations, causing "Invalid block" errors
- Ignore existing tooling in your repo
Agent Skills solve this by giving AI assistants expert-level WordPress knowledge in a format they can actually use.
Available Skills
| Skill | What it teaches |
|---|---|
| wordpress-router | Classifies WordPress repos and routes to the right workflow |
| wp-project-triage | Detects project type, tooling, and versions automatically |
| wp-block-development | Gutenberg blocks: block.json, attributes, rendering, deprecations |
| wp-block-themes | Block themes: theme.json, templates, patterns, style variations |
| wp-plugin-development | Plugin architecture, hooks, settings API, security |
| wp-rest-api | REST API routes/endpoints, schema, auth, and response shaping |
| wp-interactivity-api | Frontend interactivity with data-wp-* directives and stores |
| wp-abilities-api | Capability-based permissions and REST API authentication |
| wp-abilities-audit | Audit a plugin's REST surface and propose Abilities API registrations |
| wp-abilities-verify | Verify a plugin's Abilities API registrations against their declared annotations |
| wp-wpcli-and-ops | WP-CLI commands, automation, multisite, search-replace |
| wp-performance | Profiling, caching, database optimization, Server-Timing |
| wp-phpstan | PHPStan static analysis for WordPress projects (config, baselines, WP-specific typing) |
| wp-playground | WordPress Playground routing, CLI runs, browser previews, and snapshots |
| wpds | WordPress Design System |
| wp-plugin-directory-guidelines | WordPress Plugin Directory Guidelines |
| blueprint | WordPress Playground Blueprints for declarative environment setup |
How It Works
Each skill is a self-contained folder with instructions, references, and optional scripts:
skills/wp-block-development/
├── SKILL.md # Main instructions (when to use, procedure, verification)
├── references/ # Deep-dive docs on specific topics
│ ├── block-json.md
│ ├── deprecations.md
│ └── ...
└── scripts/ # Deterministic helpers (detection, validation)
└── list_blocks.mjs
When you ask your AI assistant to work on WordPress code, it reads these skills and follows the documented procedures rather than guessing.
Global vs. Project Scope
Skills can be installed in two scopes:
Global — installed in your home directory (e.g. ~/.claude/skills/, ~/.cursor/skills/).
- Available across all your projects automatically.
- Best for individual developers who want WordPress knowledge in every repo.
Project — installed inside a repository (e.g. .claude/skills/, .github/skills/, .cursor/skills/).
- Available only within that specific project.
- Can be committed to version control so the entire team benefits.
You can use both at the same time. When a skill exists in both scopes, the project-level version is used.
Quick Start
The fastest way to install a skill is with a single command:
npx skills add WordPress/agent-skills --skill wp-plugin-development
To see all available skills:
npx skills add WordPress/agent-skills --list
To install multiple skills at once:
npx skills add WordPress/agent-skills --skill wp-plugin-development wp-abilities-api wp-playground
Choosing a scope
npx skills add asks to choose the skill project-scoped, selecting the local scope on which the skills are installed in the local project; it can be stored at the repository (e.g. .claude/skills/, .cursor/skills/) — so the skills can be committed to version control and shared with your team.
Installing globally makes the skill available to your user (across all your projects). Adding the -g / --global flag, it will install your skill with global scope:
npx skills add WordPress/agent-skills --skill wp-plugin-development --global
Install globally for Claude Code
# Clone agent-skills
git clone https://github.com/WordPress/agent-skills.git
cd agent-skills
# Build the distribution
node shared/scripts/skillpack-build.mjs --clean
# Install all skills globally (available across all projects)
node shared/scripts/skillpack-install.mjs --global
# Or install specific skills only
node shared/scripts/skillpack-install.mjs --global --skills=wp-playground,wp-block-development
This installs skills to ~/.claude/skills/ where Claude Code will automatically discover them.
Install into your repo
# Clone agent-skills
git clone https://github.com/WordPress/agent-skills.git
cd agent-skills
# Build the distribution
node shared/scripts/skillpack-build.mjs --clean
# Install into your WordPress project
node shared/scripts/skillpack-install.mjs --dest=../your-wp-project --targets=codex,vscode,claude,cursor
This copies skills into:
.codex/skills/for OpenAI Codex.github/skills/for VS Code / GitHub Copilot.claude/skills/for Claude Code (project-level).cursor/skills/for Cursor (project-level)
Antigravity is opt-in for project-level installs. To also copy skills into .agents/skills/, include antigravity when building and installing:
node shared/scripts/skillpack-build.mjs --clean --targets=codex,vscode,claude,cursor,antigravity
node shared/scripts/skillpack-install.mjs --dest=../your-wp-project --targets=codex,vscode,claude,cursor,antigravity
Install globally for Cursor
node shared/scripts/skillpack-install.mjs --targets=cursor-global
This installs skills to ~/.cursor/skills/ where Cursor will discover them.
Install globally for Antigravity
node shared/scripts/skillpack-build.mjs --clean --targets=antigravity
node shared/scripts/skillpack-install.mjs --targets=antigravity-global
This installs skills to ~/.gemini/antigravity/skills/ where Antigravity will discover them.
Available options
# List available skills
node shared/scripts/skillpack-install.mjs --list
# Dry run (preview without installing)
node shared/scripts/skillpack-install.mjs --global --dry-run
# Install specific skills to a project (e.g. Claude + Cursor)
node shared/scripts/skillpack-install.mjs --dest=../my-repo --targets=claude,cursor --skills=wp-wpcli-and-ops
Manual installation
Copy any skill folder from skills/ into your project's instructions directory for your AI assistant.
Compatibility
- WordPress 7.0+ (PHP 7.4.0+)
- Works with any AI assistant that supports project-level instructions
Contributing
We welcome contributions! This project is a great way to share your WordPress expertise—you don't need to be a coding wizard. Most skills are written in Markdown, focusing on clear procedures and best practices.
See CONTRIBUTING.md for details on how to get started.
Quick commands:
# Scaffold a new skill
node shared/scripts/scaffold-skill.mjs <skill-name> "<description>"
# Validate skills
node eval/harness/run.mjs
Documentation
- Authoring Guide - How to create and improve skills
- Principles - Design philosophy
- Packaging - Build and distribution
- Compatibility Policy - Version targeting
License
GPL-2.0-or-later