wp-skills 1.0.0

package/skills/wp-interactivity-api/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: wp-interactivity-api
+description: "Use when building or debugging WordPress Interactivity API features (data-wp-* directives, @wordpress/interactivity store/state/actions, block viewScriptModule integration, wp_interactivity_*()) including performance, hydration, and directive behavior."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+---
+
+# WP Interactivity API
+
+## When to use
+
+Use this skill when the user mentions:
+
+- Interactivity API, `@wordpress/interactivity`,
+- `data-wp-interactive`, `data-wp-on--*`, `data-wp-bind--*`, `data-wp-context`,
+- block `viewScriptModule` / module-based view scripts,
+- hydration issues or “directives don’t fire”.
+
+## Inputs required
+
+- Repo root + triage output (`wp-project-triage`).
+- Which block/theme/plugin surfaces are affected (frontend, editor, both).
+- Any constraints: WP version, whether modules are supported in the build.
+
+## Procedure
+
+### 1) Detect existing usage + integration style
+
+Search for:
+
+- `data-wp-interactive`
+- `@wordpress/interactivity`
+- `viewScriptModule`
+
+Decide:
+
+- Is this a block providing interactivity via `block.json` view script module?
+- Is this theme-level interactivity?
+- Is this plugin-side “enhance existing markup” usage?
+
+If you’re creating a new interactive block (not just debugging), prefer the official scaffold template:
+
+- `@wordpress/create-block-interactive-template` (via `@wordpress/create-block`)
+
+### 2) Identify the store(s)
+
+Locate store definitions and confirm:
+
+- state shape,
+- actions (mutations),
+- callbacks/event handlers used by `data-wp-on--*`.
+
+### 3) Server-side rendering (best practice)
+
+**Pre-render HTML on the server** before outputting to ensure:
+
+- Correct initial state in the HTML before JavaScript loads (no layout shift).
+- SEO benefits and faster perceived load time.
+- Seamless hydration when the client-side JavaScript takes over.
+
+#### Enable server directive processing
+
+For components using `block.json`, add `supports.interactivity`:
+
+```json
+{
+  "supports": {
+    "interactivity": true
+  }
+}
+```
+
+For themes/plugins without `block.json`, use `wp_interactivity_process_directives()` to process directives.
+
+#### Initialize state/context in PHP
+
+Use `wp_interactivity_state()` to define initial global state:
+
+```php
+wp_interactivity_state( 'myPlugin', array(
+  'items'    => array( 'Apple', 'Banana', 'Cherry' ),
+  'hasItems' => true,
+));
+```
+
+For local context, use `wp_interactivity_data_wp_context()`:
+
+```php
+<?php
+$context = array( 'isOpen' => false );
+?>
+<div <?php echo wp_interactivity_data_wp_context( $context ); ?>>
+  ...
+</div>
+```
+
+#### Define derived state in PHP
+
+When derived state affects initial HTML rendering, replicate the logic in PHP:
+
+```php
+wp_interactivity_state( 'myPlugin', array(
+  'items'    => array( 'Apple', 'Banana' ),
+  'hasItems' => function() {
+    $state = wp_interactivity_state();
+    return count( $state['items'] ) > 0;
+  }
+));
+```
+
+This ensures directives like `data-wp-bind--hidden="!state.hasItems"` render correctly on first load.
+
+For detailed examples and patterns, see `references/server-side-rendering.md`.
+
+### 4) Implement or change directives safely
+
+When touching markup directives:
+
+- keep directive usage minimal and scoped,
+- prefer stable data attributes that map clearly to store state,
+- ensure server-rendered markup + client hydration align.
+
+**WordPress 6.9 changes:**
+
+- **`data-wp-ignore` is deprecated** and will be removed in future versions. It broke context inheritance and caused issues with client-side navigation. Avoid using it.
+- **Unique directive IDs**: Multiple directives of the same type can now exist on one element using the `---` separator (e.g., `data-wp-on--click---plugin-a="..."` and `data-wp-on--click---plugin-b="..."`).
+- **New TypeScript types**: `AsyncAction<ReturnType>` and `TypeYield<T>` help with async action typing.
+
+For quick directive reminders, see `references/directives-quickref.md`.
+
+### 5) Build/tooling alignment
+
+Verify the repo supports the required module build path:
+
+- if it uses `@wordpress/scripts`, prefer its conventions.
+- if it uses custom bundling, confirm module output is supported.
+
+### 6) Debug common failure modes
+
+If “nothing happens” on interaction:
+
+- confirm the `viewScriptModule` is enqueued/loaded,
+- confirm the DOM element has `data-wp-interactive`,
+- confirm the store namespace matches the directive’s value,
+- confirm there are no JS errors before hydration.
+
+See `references/debugging.md`.
+
+## Verification
+
+- `wp-project-triage` indicates `signals.usesInteractivityApi: true` after your change (if applicable).
+- Manual smoke test: directive triggers and state updates as expected.
+- If tests exist: add/extend Playwright E2E around the interaction path.
+
+## Failure modes / debugging
+
+- Directives present but inert:
+  - view script not loading, wrong module entrypoint, or missing `data-wp-interactive`.
+- Hydration mismatch / flicker:
+  - server markup differs from client expectations; simplify or align initial state.
+  - derived state not defined in PHP: use `wp_interactivity_state()` with closures.
+- Initial content missing or wrong:
+  - `supports.interactivity` not set in `block.json` (for blocks).
+  - `wp_interactivity_process_directives()` not called (for themes/plugins).
+  - state/context not initialized in PHP before render.
+- Layout shift on load:
+  - derived state like `state.hasItems` missing on server, causing `hidden` attribute to be absent.
+- Performance regressions:
+  - overly broad interactive roots; scope interactivity to smaller subtrees.
+- Client-side navigation issues (WordPress 6.9):
+  - `getServerState()` and `getServerContext()` now reset between page transitions—ensure your code doesn't assume stale values persist.
+  - Router regions now support `attachTo` for rendering overlays (modals, pop-ups) dynamically.
+
+## Escalation
+
+- If repo build constraints are unclear, ask: "Is this using `@wordpress/scripts` or a custom bundler (webpack/vite)?"
+- Consult:
+  - `references/server-side-rendering.md`
+  - `references/directives-quickref.md`
+  - `references/debugging.md`

package/skills/wp-interactivity-api/references/debugging.md

@@ -0,0 +1,29 @@
+# Debugging checklist
+
+1. Confirm the interactive root exists in the rendered HTML (`data-wp-interactive`).
+2. Confirm the view script module is loaded (network + source maps).
+3. Confirm store namespace matches what markup expects.
+4. Check console for errors before any interaction.
+5. Reduce scope:
+   - temporarily remove directives to isolate which directive/store path breaks.
+6. If hydration mismatch occurs:
+   - ensure initial state/context matches server markup.
+
+## WordPress 6.9 specific issues
+
+**State not persisting across navigation:**
+- `getServerState()` and `getServerContext()` now reset between client-side page transitions.
+- If you relied on stale values persisting, refactor to use the store's reactive state instead.
+
+**Multiple plugins conflicting on same element:**
+- Use unique directive IDs with the `---` separator to avoid attribute collisions.
+- Example: `data-wp-on--click---my-plugin="actions.handle"`
+
+**`data-wp-ignore` not working:**
+- This directive is deprecated in 6.9 and will be removed. It caused context inheritance and navigation bugs.
+- Find an alternative approach (conditional rendering, separate interactive regions).
+
+**Router regions / overlays not rendering:**
+- WordPress 6.9 adds `attachTo` property for router regions to render overlays anywhere on the page.
+- Ensure nested router regions are properly structured.
+

package/skills/wp-interactivity-api/references/directives-quickref.md

@@ -0,0 +1,30 @@
+# Directives quick reference (high level)
+
+Common directives to recognize in markup:
+
+- `data-wp-interactive`: declares an interactive region (and often a store namespace).
+- `data-wp-context`: provides server-rendered context/state.
+- `data-wp-on--event`: attaches event handlers (e.g. `click`, `submit`).
+- `data-wp-on-async--event`: async event handlers (preferred for most actions).
+- `data-wp-bind--attr`: binds DOM attributes to state.
+- `data-wp-class--name`: toggles CSS classes based on state.
+
+Use these as search anchors when triaging bugs.
+
+## Unique directive IDs (WordPress 6.9+)
+
+HTML doesn't allow duplicate attributes. To attach multiple handlers of the same type from different plugins, use the `---` separator:
+
+```html
+<button
+  data-wp-on--click---plugin-a="actions.handleA"
+  data-wp-on--click---plugin-b="actions.handleB"
+>
+```
+
+Both handlers will fire. The ID after `---` must be unique per element.
+
+## Deprecated directive
+
+- **`data-wp-ignore`**: Deprecated in WordPress 6.9. It was intended to prevent hydration of a region but broke context inheritance and client-side navigation. Will be removed in future versions. Avoid using it.
+

package/skills/wp-interactivity-api/references/server-side-rendering.md

@@ -0,0 +1,310 @@
+# Server-Side Rendering for Interactivity API
+
+- **Faster initial render**: HTML arrives ready with correct values.
+- **No layout shift**: Hidden elements stay hidden from the first paint.
+- **SEO benefits**: Search engines see fully rendered content.
+- **Graceful degradation**: Content displays correctly even before JavaScript loads.
+
+## Setup Requirements
+
+### 1. Enable Server Directive Processing
+
+**For components using `block.json`:**
+
+```json
+{
+  "supports": {
+    "interactivity": true
+  }
+}
+```
+
+**For themes/plugins without `block.json`:**
+
+Use `wp_interactivity_process_directives()` to manually process directives (see "Themes and Plugins without block.json" section below).
+
+### 2. Initialize Global State with `wp_interactivity_state()`
+
+Define initial state values in PHP before rendering:
+
+```php
+wp_interactivity_state( 'myPlugin', array(
+  'fruits'    => array( 'Apple', 'Banana', 'Cherry' ),
+  'isLoading' => false,
+  'count'     => 3,
+));
+```
+
+The state is serialized and available to client JavaScript automatically.
+
+### 3. Initialize Local Context with `wp_interactivity_data_wp_context()`
+
+For element-scoped context:
+
+```php
+<?php
+$context = array(
+  'isOpen'   => false,
+  'itemId'   => 42,
+  'itemName' => 'Example',
+);
+?>
+<div
+  data-wp-interactive="myPlugin"
+  <?php echo wp_interactivity_data_wp_context( $context ); ?>
+>
+  <button data-wp-on-async--click="actions.toggle">
+    Toggle
+  </button>
+  <div data-wp-bind--hidden="!context.isOpen">
+    Content for <?php echo esc_html( $context['itemName'] ); ?>
+  </div>
+</div>
+```
+
+## Derived State on the Server
+
+When derived state affects the initial HTML, define it in PHP to avoid layout shifts.
+
+### Static Derived State
+
+When the derived value is known at render time:
+
+```php
+$fruits    = array( 'Apple', 'Banana', 'Cherry' );
+$hasFruits = count( $fruits ) > 0;
+
+wp_interactivity_state( 'myPlugin', array(
+  'fruits'    => $fruits,
+  'hasFruits' => $hasFruits,
+));
+```
+
+### Dynamic Derived State (using closures)
+
+When the value depends on context (e.g., inside `data-wp-each` loops):
+
+```php
+wp_interactivity_state( 'myPlugin', array(
+  'fruits'       => array( 'apple', 'banana', 'cherry' ),
+  'shoppingList' => array( 'apple', 'cherry' ),
+  'onShoppingList' => function() {
+    $state   = wp_interactivity_state();
+    $context = wp_interactivity_get_context();
+    return in_array( $context['item'], $state['shoppingList'] ) ? 'Yes' : 'No';
+  },
+));
+```
+
+The closure is evaluated during directive processing for each element.
+
+## Complete Example: List with Server Rendering
+
+### PHP (render callback or template)
+
+```php
+<?php
+$fruits = array( 'Apple', 'Banana', 'Cherry' );
+
+wp_interactivity_state( 'myFruitPlugin', array(
+  'fruits'    => $fruits,
+  'hasFruits' => count( $fruits ) > 0,
+  'mango'     => __( 'Mango' ),
+));
+?>
+
+<div data-wp-interactive="myFruitPlugin">
+  <button data-wp-on-async--click="actions.addMango">
+    <?php esc_html_e( 'Add Mango' ); ?>
+  </button>
+  <button data-wp-on-async--click="actions.clearAll">
+    <?php esc_html_e( 'Clear All' ); ?>
+  </button>
+
+  <ul data-wp-bind--hidden="!state.hasFruits">
+    <template data-wp-each="state.fruits">
+      <li data-wp-text="context.item"></li>
+    </template>
+  </ul>
+
+  <p data-wp-bind--hidden="state.hasFruits">
+    <?php esc_html_e( 'No fruits available.' ); ?>
+  </p>
+</div>
+```
+
+### JavaScript (view.js)
+
+```javascript
+import { store, getContext } from '@wordpress/interactivity';
+
+const { state } = store( 'myFruitPlugin', {
+  state: {
+    get hasFruits() {
+      return state.fruits.length > 0;
+    },
+  },
+  actions: {
+    addMango() {
+      state.fruits.push( state.mango );
+    },
+    clearAll() {
+      state.fruits = [];
+    },
+  },
+});
+```
+
+### Rendered Output (initial HTML)
+
+```html
+<div data-wp-interactive="myFruitPlugin">
+  <button data-wp-on-async--click="actions.addMango">Add Mango</button>
+  <button data-wp-on-async--click="actions.clearAll">Clear All</button>
+
+  <ul>
+    <li>Apple</li>
+    <li>Banana</li>
+    <li>Cherry</li>
+  </ul>
+
+  <p hidden>No fruits available.</p>
+</div>
+```
+
+The `hidden` attribute is added server-side because `state.hasFruits` is true.
+
+## Serializing Values for Client Use
+
+Use `wp_interactivity_state()` to pass server values to client JavaScript:
+
+### Translations
+
+```php
+wp_interactivity_state( 'myPlugin', array(
+  'labels' => array(
+    'add'    => __( 'Add Item', 'textdomain' ),
+    'remove' => __( 'Remove Item', 'textdomain' ),
+    'empty'  => __( 'No items found', 'textdomain' ),
+  ),
+));
+```
+
+### Ajax URLs and Nonces
+
+```php
+wp_interactivity_state( 'myPlugin', array(
+  'ajaxUrl' => admin_url( 'admin-ajax.php' ),
+  'nonce'   => wp_create_nonce( 'myPlugin_nonce' ),
+  'restUrl' => rest_url( 'myPlugin/v1/' ),
+));
+```
+
+### Client Usage
+
+```javascript
+const { state } = store( 'myPlugin', {
+  actions: {
+    *fetchData() {
+      const formData = new FormData();
+      formData.append( 'action', 'my_action' );
+      formData.append( '_ajax_nonce', state.nonce );
+
+      const response = yield fetch( state.ajaxUrl, {
+        method: 'POST',
+        body: formData,
+      });
+      return yield response.json();
+    },
+  },
+});
+```
+
+## Themes and Plugins without block.json
+
+For themes or plugins not using `block.json`, use `wp_interactivity_process_directives()`:
+
+```php
+<?php
+wp_interactivity_state( 'myTheme', array(
+  'menuOpen' => false,
+));
+
+ob_start();
+?>
+
+<nav
+  data-wp-interactive="myTheme"
+  data-wp-class--is-open="state.menuOpen"
+>
+  <button data-wp-on-async--click="actions.toggleMenu">
+    Menu
+  </button>
+  <ul data-wp-bind--hidden="!state.menuOpen">
+    <li><a href="/">Home</a></li>
+    <li><a href="/about">About</a></li>
+  </ul>
+</nav>
+
+<?php
+$html = ob_get_clean();
+echo wp_interactivity_process_directives( $html );
+```
+
+Only call `wp_interactivity_process_directives()` once at the outermost template level.
+
+## PHP Helper Functions Reference
+
+| Function | Purpose |
+|----------|---------|
+| `wp_interactivity_state( $namespace, $state )` | Initialize/get global state for a namespace |
+| `wp_interactivity_data_wp_context( $context )` | Generate `data-wp-context` attribute |
+| `wp_interactivity_get_context( $namespace )` | Get current context during directive processing |
+| `wp_interactivity_process_directives( $html )` | Manually process directives (themes/plugins) |
+
+## Common Pitfalls
+
+### Server Directive Processing Not Enabled
+
+**For `block.json` users:** Without `supports.interactivity`, directives are not processed:
+
+```json
+{
+  "supports": {
+    "interactivity": true
+  }
+}
+```
+
+**For themes/plugins:** Ensure `wp_interactivity_process_directives()` is called on the HTML output.
+
+### Derived State Missing on Server
+
+If `state.hasFruits` is only defined in JavaScript, the `hidden` attribute won't be set:
+
+```html
+<!-- Without server state: shows briefly then hides (layout shift) -->
+<p data-wp-bind--hidden="state.hasFruits">No fruits</p>
+```
+
+### State Not Matching Client Expectations
+
+Ensure PHP and JavaScript derived state logic matches:
+
+```php
+// PHP
+'hasFruits' => count( $fruits ) > 0,
+```
+
+```javascript
+// JavaScript - must match PHP logic
+get hasFruits() {
+  return state.fruits.length > 0;
+}
+```
+
+## External References
+
+- [WordPress: Server-side rendering](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/core-concepts/server-side-rendering/)
+- [WordPress: Understanding global state, local context and derived state](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/core-concepts/undestanding-global-state-local-context-and-derived-state/)
+- [WordPress: Interactivity API Reference](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/api-reference/)

package/skills/wp-performance/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: wp-performance
+description: "Use when investigating or improving WordPress performance (backend-only agent): profiling and measurement (WP-CLI profile/doctor, Server-Timing, Query Monitor via REST headers), database/query optimization, autoloaded options, object caching, cron, HTTP API calls, and safe verification."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Backend-only agent; prefers WP-CLI (doctor/profile) when available."
+---
+
+# WP Performance (backend-only)
+
+## When to use
+
+Use this skill when:
+
+- a WordPress site/page/endpoint is slow (frontend TTFB, admin, REST, WP-Cron)
+- you need a profiling plan and tooling recommendations (WP-CLI profile/doctor, Query Monitor, Xdebug/XHProf, APMs)
+- you’re optimizing DB queries, autoloaded options, object caching, cron tasks, or remote HTTP calls
+
+This skill assumes the agent cannot use a browser UI. Prefer WP-CLI, logs, and HTTP requests.
+
+## Inputs required
+
+- Environment and safety: dev/staging/prod, any restrictions (no writes, no plugin installs).
+- How to target the install:
+  - WP root `--path=<path>`
+  - (multisite/site targeting) `--url=<url>`
+- The performance symptom and scope:
+  - which URL/REST route/admin screen
+  - when it happens (always vs sporadic; logged-in vs logged-out)
+
+## Procedure
+
+### 0) Guardrails: measure first, avoid risky ops
+
+1. Confirm whether you may run write operations (plugin installs, config changes, cache flush).
+2. Pick a reproducible target (URL or REST route) and capture a baseline:
+   - TTFB/time with `curl` if possible
+   - WP-CLI profiling if available
+
+Read:
+- `references/measurement.md`
+
+### 1) Generate a backend-only performance report (deterministic)
+
+Run:
+
+- `node skills/wp-performance/scripts/perf_inspect.mjs --path=<path> [--url=<url>]`
+
+This detects:
+
+- WP-CLI availability and core version
+- whether `wp doctor` / `wp profile` are available
+- autoloaded options size (if possible)
+- object-cache drop-in presence
+
+### 2) Fast wins: run diagnostics before deep profiling
+
+If you have WP-CLI access, prefer:
+
+- `wp doctor check`
+
+It catches common production foot-guns (autoload bloat, SAVEQUERIES/WP_DEBUG, plugin counts, updates).
+
+Read:
+- `references/wp-cli-doctor.md`
+
+### 3) Deep profiling (no browser required)
+
+Preferred order:
+
+1. `wp profile stage` to see where time goes (bootstrap/main_query/template).
+2. `wp profile hook` (optionally with `--url=`) to find slow hooks/callbacks.
+3. `wp profile eval` for targeted code paths.
+
+Read:
+- `references/wp-cli-profile.md`
+
+### 4) Query Monitor (backend-only usage)
+
+Query Monitor is normally UI-driven, but it can be used headlessly via REST API response headers and `_envelope` responses:
+
+- Authenticate (nonce or Application Password).
+- Request REST responses and inspect headers (`x-qm-*`) and/or the `qm` property when using `?_envelope`.
+
+Read:
+- `references/query-monitor-headless.md`
+
+### 5) Fix by category (choose the dominant bottleneck)
+
+Use the profile output to pick *one* primary bottleneck category:
+
+- **DB queries** → reduce query count, fix N+1 patterns, improve indexes, avoid expensive meta queries.
+  - `references/database.md`
+- **Autoloaded options** → identify the biggest autoloaded options and stop autoloading large blobs.
+  - `references/autoload-options.md`
+- **Object cache misses** → introduce caching or fix cache key/group usage; add persistent object cache where appropriate.
+  - `references/object-cache.md`
+- **Remote HTTP calls** → add timeouts, caching, batching; avoid calling remote APIs on every request.
+  - `references/http-api.md`
+- **Cron** → reduce due-now spikes, de-duplicate events, move heavy tasks out of request paths.
+  - `references/cron.md`
+
+### 6) Verify (repeat the same measurement)
+
+- Re-run the same `wp profile` / `wp doctor` / REST request.
+- Confirm the performance delta and that behavior is unchanged.
+- If the fix is risky, ship behind a feature flag or staged rollout when possible.
+
+## WordPress 6.9 performance improvements
+
+Be aware of these 6.9 changes when profiling:
+
+**On-demand CSS for classic themes:**
+- Classic themes now get on-demand CSS loading (previously only block themes had this).
+- Reduces CSS payload by 30-65% by only loading styles for blocks actually used on the page.
+- If you're profiling a classic theme, this should already be helping.
+
+**Block themes with no render-blocking resources:**
+- Block themes that don't define custom stylesheets (like Twenty Twenty-Three/Four) can now load with zero render-blocking CSS.
+- Styles come from global styles (theme.json) and separate block styles, all inlined.
+- This significantly improves LCP (Largest Contentful Paint).
+
+**Inline CSS limit increased:**
+- The threshold for inlining small stylesheets has been raised, reducing render-blocking resources.
+
+Reference: https://make.wordpress.org/core/2025/11/18/wordpress-6-9-frontend-performance-field-guide/
+
+## Verification
+
+- Baseline vs after numbers are captured (same environment, same URL/route).
+- `wp doctor check` is clean (or improved) when applicable.
+- No new PHP errors or warnings in logs.
+- No cache flush is required for correctness (cache flush should be last resort).
+
+## Failure modes / debugging
+
+- “No change” after code changes:
+  - you measured a different URL/site (`--url` mismatch), caches masked results, or opcode cache is stale
+- Profiling data is noisy:
+  - eliminate background tasks, test with warmed caches, run multiple samples
+- `SAVEQUERIES`/Query Monitor causes overhead:
+  - don’t run in production unless explicitly approved
+
+## Escalation
+
+- If this is production and you don’t have explicit approval, do not:
+  - install plugins, enable `SAVEQUERIES`, run load tests, or flush caches during traffic
+- If you need system-level profiling (APM, PHP profiler extensions), coordinate with ops/hosting.