claude-plugin-wordpress-manager 1.4.0

package/servers/wp-rest-bridge/build/wordpress.js

@@ -0,0 +1,305 @@
+// src/wordpress.ts - Multi-site WordPress REST API client
+import axios from 'axios';
+// ── Concurrency Limiter ──────────────────────────────────────────────
+// Simple FIFO semaphore to cap concurrent requests per site
+class ConcurrencyLimiter {
+    maxConcurrent;
+    running = 0;
+    queue = [];
+    constructor(maxConcurrent) {
+        this.maxConcurrent = maxConcurrent;
+    }
+    async acquire() {
+        if (this.running < this.maxConcurrent) {
+            this.running++;
+            return;
+        }
+        return new Promise((resolve) => {
+            this.queue.push(() => {
+                this.running++;
+                resolve();
+            });
+        });
+    }
+    release() {
+        this.running--;
+        const next = this.queue.shift();
+        if (next)
+            next();
+    }
+}
+// ── Module State ─────────────────────────────────────────────────────
+const siteClients = new Map();
+const siteLimiters = new Map();
+let activeSiteId = '';
+const MAX_CONCURRENT_PER_SITE = 5;
+const DEFAULT_TIMEOUT_MS = parseInt(process.env.WP_REQUEST_TIMEOUT_MS || '30000', 10);
+const MAX_RETRIES = 3;
+// HTTP status codes that are safe to retry
+const RETRYABLE_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504]);
+// Network error codes that are safe to retry
+const RETRYABLE_ERROR_CODES = new Set(['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND']);
+// ── Initialization ───────────────────────────────────────────────────
+/**
+ * Parse WP_SITES_CONFIG JSON and initialize all site clients
+ */
+export async function initWordPress() {
+    const sitesJson = process.env.WP_SITES_CONFIG;
+    const defaultSite = process.env.WP_DEFAULT_SITE;
+    if (!sitesJson) {
+        // Fallback to legacy single-site env vars
+        const url = process.env.WORDPRESS_API_URL;
+        const username = process.env.WORDPRESS_USERNAME;
+        const password = process.env.WORDPRESS_PASSWORD;
+        if (!url) {
+            throw new Error('No WordPress site configured. Set WP_SITES_CONFIG or WORDPRESS_API_URL.');
+        }
+        const siteId = 'default';
+        await initSiteClient(siteId, url, username || '', password || '');
+        activeSiteId = siteId;
+        logToStderr(`Initialized single site: ${url}`);
+        return;
+    }
+    let sites;
+    try {
+        sites = JSON.parse(sitesJson);
+    }
+    catch {
+        throw new Error('Invalid WP_SITES_CONFIG JSON format');
+    }
+    if (sites.length === 0) {
+        throw new Error('WP_SITES_CONFIG contains no sites');
+    }
+    for (const site of sites) {
+        await initSiteClient(site.id, site.url, site.username, site.password);
+        logToStderr(`Initialized site: ${site.id} (${site.url})`);
+    }
+    activeSiteId = defaultSite || sites[0].id;
+    logToStderr(`Active site: ${activeSiteId}`);
+}
+/**
+ * Initialize a single site's Axios client.
+ * baseURL now points to {site}/wp-json/ so that tools can use any namespace.
+ */
+async function initSiteClient(id, url, username, password) {
+    let baseURL = url.endsWith('/') ? url : `${url}/`;
+    // Strip existing wp-json path variants so we normalize to just /wp-json/
+    const wpJsonIdx = baseURL.indexOf('/wp-json');
+    if (wpJsonIdx !== -1) {
+        baseURL = baseURL.substring(0, wpJsonIdx + 1);
+    }
+    baseURL = baseURL + 'wp-json/';
+    const config = {
+        baseURL,
+        headers: { 'Content-Type': 'application/json' },
+        timeout: DEFAULT_TIMEOUT_MS,
+    };
+    if (username && password) {
+        const auth = Buffer.from(`${username}:${password}`).toString('base64');
+        config.headers = {
+            ...config.headers,
+            'Authorization': `Basic ${auth}`,
+        };
+    }
+    const client = axios.create(config);
+    // Verify connection (using wp/v2 namespace)
+    try {
+        await client.get('wp/v2');
+    }
+    catch (error) {
+        logToStderr(`Warning: Could not verify connection to ${url}: ${error.message}`);
+        // Don't throw - the site might become available later
+    }
+    siteClients.set(id, client);
+    siteLimiters.set(id, new ConcurrencyLimiter(MAX_CONCURRENT_PER_SITE));
+}
+// ── Site Management ──────────────────────────────────────────────────
+/**
+ * Get the active site's client, or a specific site's client
+ */
+function getClient(siteId) {
+    const id = siteId || activeSiteId;
+    const client = siteClients.get(id);
+    if (!client) {
+        const available = Array.from(siteClients.keys()).join(', ');
+        throw new Error(`Site "${id}" not found. Available sites: ${available}`);
+    }
+    return client;
+}
+function getLimiter(siteId) {
+    const id = siteId || activeSiteId;
+    let limiter = siteLimiters.get(id);
+    if (!limiter) {
+        limiter = new ConcurrencyLimiter(MAX_CONCURRENT_PER_SITE);
+        siteLimiters.set(id, limiter);
+    }
+    return limiter;
+}
+/**
+ * Switch the active site
+ */
+export function switchSite(siteId) {
+    if (!siteClients.has(siteId)) {
+        const available = Array.from(siteClients.keys()).join(', ');
+        throw new Error(`Site "${siteId}" not found. Available: ${available}`);
+    }
+    activeSiteId = siteId;
+    return activeSiteId;
+}
+/**
+ * List all configured sites
+ */
+export function listSites() {
+    return Array.from(siteClients.keys());
+}
+/**
+ * Get the active site ID
+ */
+export function getActiveSite() {
+    return activeSiteId;
+}
+// ── Logging ──────────────────────────────────────────────────────────
+/**
+ * Log to stderr (safe for MCP stdio transport)
+ */
+export function logToStderr(message) {
+    const timestamp = new Date().toISOString();
+    process.stderr.write(`[${timestamp}] ${message}\n`);
+}
+// Keep backward-compatible alias
+export const logToFile = logToStderr;
+// ── Retry Logic ──────────────────────────────────────────────────────
+function isRetryableError(error, method) {
+    // Network errors are always retryable
+    if (error.code && RETRYABLE_ERROR_CODES.has(error.code)) {
+        return true;
+    }
+    const status = error.response?.status;
+    if (!status)
+        return false;
+    // For non-GET (mutating) methods, only retry on 429 (rate limit) — not 5xx
+    // to avoid duplicate side-effects
+    if (method !== 'GET') {
+        return status === 429;
+    }
+    return RETRYABLE_STATUS_CODES.has(status);
+}
+function getRetryDelay(attempt, error) {
+    // Respect Retry-After header on 429
+    const retryAfter = error.response?.headers?.['retry-after'];
+    if (retryAfter) {
+        const seconds = parseInt(retryAfter, 10);
+        if (!isNaN(seconds))
+            return seconds * 1000;
+    }
+    // Exponential backoff: 1s, 2s, 4s + jitter (0–500ms)
+    const base = Math.pow(2, attempt) * 1000;
+    const jitter = Math.random() * 500;
+    return base + jitter;
+}
+/**
+ * Make a request to the WordPress API (active site or specific site).
+ * Includes automatic retry with exponential backoff and concurrency limiting.
+ */
+export async function makeWordPressRequest(method, endpoint, data, options) {
+    const siteId = options?.siteId || activeSiteId;
+    const client = getClient(siteId);
+    const limiter = getLimiter(siteId);
+    const namespace = options?.namespace || 'wp/v2';
+    // Build the full path: {namespace}/{endpoint}
+    const cleanEndpoint = endpoint.startsWith('/') ? endpoint.substring(1) : endpoint;
+    const path = `${namespace}/${cleanEndpoint}`;
+    await limiter.acquire();
+    try {
+        return await executeWithRetry(client, method, path, data, siteId, options);
+    }
+    finally {
+        limiter.release();
+    }
+}
+async function executeWithRetry(client, method, path, data, siteId, options) {
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const requestConfig = {
+                method,
+                url: path,
+                headers: options?.headers || {},
+            };
+            if (options?.timeout) {
+                requestConfig.timeout = options.timeout;
+            }
+            if (method === 'GET') {
+                requestConfig.params = data;
+            }
+            else if (options?.isFormData) {
+                requestConfig.data = data;
+            }
+            else if (data) {
+                requestConfig.data = data;
+            }
+            const response = await client.request(requestConfig);
+            // Handle pagination metadata extraction
+            if (options?.includePagination && method === 'GET') {
+                const total = parseInt(response.headers['x-wp-total'] || '0', 10);
+                const totalPages = parseInt(response.headers['x-wp-totalpages'] || '0', 10);
+                const page = data?.page || 1;
+                const perPage = data?.per_page || 10;
+                return {
+                    items: response.data,
+                    pagination: { total, totalPages, page, perPage },
+                };
+            }
+            return options?.rawResponse ? response : response.data;
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt < MAX_RETRIES && isRetryableError(error, method)) {
+                const delay = getRetryDelay(attempt, error);
+                const status = error.response?.status || error.code || 'unknown';
+                logToStderr(`[${siteId}] Retry ${attempt + 1}/${MAX_RETRIES} for ${method} ${path} (${status}), waiting ${Math.round(delay)}ms`);
+                await sleep(delay);
+                continue;
+            }
+            break;
+        }
+    }
+    // All retries exhausted or non-retryable error
+    const errorMessage = lastError.response?.data?.message || lastError.message;
+    logToStderr(`[${siteId}] Error ${method} ${path}: ${errorMessage}`);
+    throw lastError;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ── Plugin Repository (External API) ────────────────────────────────
+/**
+ * Search the WordPress.org Plugin Repository
+ */
+export async function searchWordPressPluginRepository(searchQuery, page = 1, perPage = 10) {
+    const apiUrl = 'https://api.wordpress.org/plugins/info/1.2/';
+    const requestData = {
+        action: 'query_plugins',
+        request: {
+            search: searchQuery,
+            page,
+            per_page: perPage,
+            fields: {
+                description: true,
+                sections: false,
+                tested: true,
+                requires: true,
+                rating: true,
+                downloaded: true,
+                downloadlink: true,
+                last_updated: true,
+                homepage: true,
+                tags: true,
+            },
+        },
+    };
+    const response = await axios.post(apiUrl, requestData, {
+        headers: { 'Content-Type': 'application/json' },
+    });
+    return response.data;
+}

package/servers/wp-rest-bridge/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "wp-rest-bridge",
+  "version": "1.1.0",
+  "description": "Lightweight MCP server bridging WordPress REST API for multi-site management",
+  "type": "module",
+  "main": "./build/server.js",
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "start": "node ./build/server.js",
+    "dev": "tsx watch src/server.ts",
+    "clean": "rm -rf build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "axios": "^1.7.9",
+    "form-data": "^4.0.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}

package/skills/wordpress-router/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: wordpress-router
+description: “Use when the user asks about WordPress — whether development (plugins, themes,
+  blocks, REST API) or operations (deploy, audit, backup, migrate, content management).
+  Classifies the task and routes to the correct development or operational skill/agent.”
+compatibility: “Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI.”
+version: 1.0.0
+source: “WordPress/agent-skills (GPL-2.0-or-later) + wordpress-manager extensions”
+---
+
+# WordPress Router
+
+## When to use
+
+Use this skill at the start of most WordPress tasks to:
+
+- identify what kind of WordPress task this is (development vs operations),
+- for development: classify the repo (plugin vs theme vs block theme vs WP core),
+- for operations: identify the operation type (deploy, audit, backup, migrate, content),
+- route to the most relevant skill(s) and/or agent(s).
+
+## Inputs required
+
+- Repo root (for development tasks) or site identifier (for operational tasks).
+- The user’s intent and any constraints.
+
+## Procedure
+
+### 1) Determine task category
+
+**Development tasks** (code changes to WordPress projects):
+- Creating/modifying blocks, themes, plugins, REST endpoints
+- Building UI with WordPress Design System (WPDS)
+- Static analysis, build tooling, testing
+- Sandbox testing via WordPress Playground
+- Route via project triage → development skills
+
+**Operational tasks** (managing live WordPress sites):
+- Deploying, auditing, backing up, migrating, managing content
+- Route directly → operational skills and agents
+
+### 2) For Development tasks
+
+1. Run the project triage script:
+   - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
+2. Classify from triage output.
+3. Route to development skills — see `references/decision-tree.md`.
+
+### 3) For Operational tasks
+
+Route by intent keywords:
+
+- **Deploy / push / production** → `wp-deploy` skill + `wp-deployment-engineer` agent
+- **Audit / security / health check / SEO** → `wp-audit` skill + `wp-security-auditor` agent
+- **Backup / restore / snapshot** → `wp-backup` skill
+- **Migrate / move / transfer / clone** → `wp-migrate` skill
+- **Content / blog post / pages / categories** → `wp-content` skill + `wp-content-strategist` agent
+- **Performance / slow / PageSpeed / optimize** → `wp-audit` skill + `wp-performance-optimizer` agent
+- **Site status / plugins / users / multi-site** → `wp-site-manager` agent
+
+### 4) Apply guardrails
+
+- For development: prefer repo’s existing tooling and conventions.
+- For operations: confirm target site, verify backups, get user confirmation for destructive ops.
+
+## Verification
+
+- Re-run triage after structural changes (development).
+- Verify site connectivity before operations.
+
+## Failure modes / debugging
+
+- Development: If triage reports `kind: unknown`, inspect root files.
+- Operations: If site unreachable, check `WP_SITES_CONFIG` and credentials.
+
+## Escalation
+
+- If routing is ambiguous, ask: “Are you looking to develop/modify WordPress code, or manage/operate a live WordPress site?”

package/skills/wordpress-router/references/decision-tree.md

@@ -0,0 +1,88 @@
+# Router decision tree (v2 — unified development + operations)
+
+This routing guide covers both WordPress **development** and **operations** workflows.
+
+## Step 0: determine task category
+
+Before repo triage, classify the user’s intent:
+
+- **Development** (modifying code) → proceed to Step 1
+- **Operations** (managing live sites) → skip to Step 2b
+
+Keywords that indicate **operations**:
+deploy, push to production, audit, security check, backup, restore, migrate, move site, create post, manage content, site status, check plugins, performance check, SEO audit
+
+Keywords that indicate **development**:
+create block, block.json, theme.json, register_rest_route, plugin development, hooks, PHPStan, build, test, scaffold
+
+## Step 1: classify repo kind (from triage — development only)
+
+Run `wp-project-triage` first, then use `triage.project.kind`:
+
+- `wp-core` → WordPress core checkout work.
+- `wp-site` → full site repo (wp-content present).
+- `wp-block-theme` → theme.json/templates/patterns workflows.
+- `wp-theme` → classic theme workflows.
+- `wp-block-plugin` → Gutenberg block development in a plugin.
+- `wp-plugin` / `wp-mu-plugin` → plugin workflows.
+- `gutenberg` → Gutenberg monorepo workflows.
+
+Priority: `gutenberg` > `wp-core` > `wp-site` > `wp-block-theme` > `wp-block-plugin` > `wp-theme` > `wp-plugin`.
+
+## Step 2a: route by development intent (keywords)
+
+- **Interactivity API / data-wp-* / @wordpress/interactivity / viewScriptModule**
+  → `wp-interactivity-api`
+- **Abilities API / wp_register_ability / wp-abilities/v1**
+  → `wp-abilities-api`
+- **Blocks / block.json / registerBlockType / attributes / save serialization**
+  → `wp-block-development`
+- **theme.json / Global Styles / templates/*.html / patterns/**
+  → `wp-block-themes`
+- **Plugin architecture / hooks / activation / Settings API / admin pages**
+  → `wp-plugin-development`
+- **REST endpoint / register_rest_route / permission_callback**
+  → `wp-rest-api`
+- **WP-CLI / wp-cli.yml / commands**
+  → `wp-wpcli-and-ops`
+- **PHPStan / static analysis / phpstan.neon**
+  → `wp-phpstan`
+- **Performance profiling / query optimization / editor slowness**
+  → `wp-performance` (backend profiling with WP-CLI doctor/profile)
+- **UI components / design tokens / @wordpress/components / @wordpress/ui / WPDS**
+  → `wpds` (WordPress Design System)
+- **Playground / disposable WP / blueprint / sandbox / test environment / version switching**
+  → `wp-playground`
+
+## Step 2b: route by operational intent (keywords)
+
+- **Deploy / push / production / Hostinger**
+  → `wp-deploy` skill + `wp-deployment-engineer` agent
+- **Audit / security check / vulnerability / hacked / health check**
+  → `wp-audit` skill + `wp-security-auditor` agent
+- **Backup / snapshot / disaster recovery / restore**
+  → `wp-backup` skill
+- **Migrate / move / transfer / clone site / change hosting**
+  → `wp-migrate` skill
+- **Create post / write content / manage pages / categories / SEO content**
+  → `wp-content` skill + `wp-content-strategist` agent
+- **Slow site / PageSpeed / Core Web Vitals / optimize performance**
+  → `wp-audit` skill (performance scope) + `wp-performance-optimizer` agent
+- **Site status / list plugins / manage users / multi-site coordination**
+  → `wp-site-manager` agent
+- **DNS / domain / SSL / hosting configuration**
+  → `wp-site-manager` agent (Hostinger MCP tools)
+
+## Step 3: guardrails checklist (always)
+
+### Development guardrails
+- Verify detected tooling before suggesting commands (Composer vs npm/yarn/pnpm).
+- Prefer existing lint/test scripts if present.
+- If version constraints aren’t detectable, ask for target WP core and PHP versions.
+
+### Operations guardrails
+- Confirm target site before any operation.
+- Verify backups exist before destructive operations (deploy, migrate, restore).
+- Get explicit user confirmation before publishing, deleting, or modifying live content.
+- Never deactivate plugins or delete content without listing dependencies first.
+- For multi-site operations, announce which site you’re operating on.

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

@@ -0,0 +1,97 @@
+---
+name: wp-abilities-api
+description: "Use when working with the WordPress Abilities API (wp_register_ability, wp_register_ability_category, /wp-json/wp-abilities/v1/*, @wordpress/abilities) including defining abilities, categories, meta, REST exposure, and permissions checks for clients."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+version: 1.0.0
+source: "WordPress/agent-skills (GPL-2.0-or-later)"
+---
+
+# WP Abilities API
+
+## When to use
+
+Use this skill when the task involves:
+
+- registering abilities or ability categories in PHP,
+- exposing abilities to clients via REST (`wp-abilities/v1`),
+- consuming abilities in JS (notably `@wordpress/abilities`),
+- diagnosing “ability doesn’t show up” / “client can’t see ability” / “REST returns empty”.
+
+## Inputs required
+
+- Repo root (run `wp-project-triage` first if you haven’t).
+- Target WordPress version(s) and whether this is WP core or a plugin/theme.
+- Where the change should live (plugin vs theme vs mu-plugin).
+
+## Procedure
+
+### 1) Confirm availability and version constraints
+
+- If this is WP core work, check `signals.isWpCoreCheckout` and `versions.wordpress.core`.
+- If the project targets WP < 6.9, you may need the Abilities API plugin/package rather than relying on core.
+
+### 2) Find existing Abilities usage
+
+Search for these in the repo:
+
+- `wp_register_ability(`
+- `wp_register_ability_category(`
+- `wp_abilities_api_init`
+- `wp_abilities_api_categories_init`
+- `wp-abilities/v1`
+- `@wordpress/abilities`
+
+If none exist, decide whether you’re introducing Abilities API fresh (new registrations + client consumption) or only consuming.
+
+### 3) Register categories (optional)
+
+If you need a logical grouping, register an ability category early (see `references/php-registration.md`).
+
+### 4) Register abilities (PHP)
+
+Implement the ability in PHP registration with:
+
+- stable `id` (namespaced),
+- `label`/`description`,
+- `category`,
+- `meta`:
+  - add `readonly: true` when the ability is informational,
+  - set `show_in_rest: true` for abilities you want visible to clients.
+
+Use the documented init hooks for Abilities API registration so they load at the right time (see `references/php-registration.md`).
+
+### 5) Confirm REST exposure
+
+- Verify the REST endpoints exist and return expected results (see `references/rest-api.md`).
+- If the client still can’t see the ability, confirm `meta.show_in_rest` is enabled and you’re querying the right endpoint.
+
+### 6) Consume from JS (if needed)
+
+- Prefer `@wordpress/abilities` APIs for client-side access and checks.
+- Ensure build tooling includes the dependency and the project’s build pipeline bundles it.
+
+## Verification
+
+- `wp-project-triage` indicates `signals.usesAbilitiesApi: true` after your change (if applicable).
+- REST check (in a WP environment): endpoints under `wp-abilities/v1` return your ability and category when expected.
+- If the repo has tests, add/update coverage near:
+  - PHP: ability registration and meta exposure
+  - JS: ability consumption and UI gating
+
+## Failure modes / debugging
+
+- Ability never appears:
+  - registration code not running (wrong hook / file not loaded),
+  - missing `meta.show_in_rest`,
+  - incorrect category/ID mismatch.
+- REST shows ability but JS doesn’t:
+  - wrong REST base/namespace,
+  - JS dependency not bundled,
+  - caching (object/page caches) masking changes.
+
+## Escalation
+
+- If you’re uncertain about version support, confirm target WP core versions and whether Abilities API is expected from core or as a plugin.
+- For canonical details, consult:
+  - `references/rest-api.md`
+  - `references/php-registration.md`

package/skills/wp-abilities-api/references/php-registration.md

@@ -0,0 +1,67 @@
+# PHP registration quick guide
+
+Key concepts and entrypoints for the WordPress Abilities API:
+
+- Register ability categories and abilities in PHP.
+- Use the Abilities API init hooks to ensure registration occurs at the right lifecycle time.
+
+## Hook order (critical)
+
+**Categories must be registered before abilities.** Use the correct hooks:
+
+1. `wp_abilities_api_categories_init` — Register categories here first.
+2. `wp_abilities_api_init` — Register abilities here (after categories exist).
+
+**Warning:** Registering abilities outside `wp_abilities_api_init` triggers `_doing_it_wrong()` and the registration will fail.
+
+```php
+// 1. Register category first
+add_action( 'wp_abilities_api_categories_init', function() {
+    wp_register_ability_category( 'my-plugin', [
+        'label' => __( 'My Plugin', 'my-plugin' ),
+    ] );
+} );
+
+// 2. Then register abilities
+add_action( 'wp_abilities_api_init', function() {
+    wp_register_ability( 'my-plugin/get-info', [
+        'label'       => __( 'Get Site Info', 'my-plugin' ),
+        'description' => __( 'Returns basic site information.', 'my-plugin' ),
+        'category'    => 'my-plugin',
+        'callback'    => 'my_plugin_get_info_callback',
+        'meta'        => [ 'show_in_rest' => true ],
+    ] );
+} );
+```
+
+## Common primitives
+
+- `wp_register_ability_category( $category_id, $args )`
+- `wp_register_ability( $ability_id, $args )`
+
+## Key arguments for `wp_register_ability()`
+
+| Argument | Description |
+|----------|-------------|
+| `label` | Human-readable name for UI (e.g., command palette) |
+| `description` | What the ability does |
+| `category` | Category ID (must be registered first) |
+| `callback` | Function that executes the ability |
+| `input_schema` | JSON Schema for expected input (enables validation) |
+| `output_schema` | JSON Schema for returned output |
+| `permission_callback` | Optional function to check if current user can execute |
+| `meta.show_in_rest` | Set `true` to expose via REST API |
+| `meta.readonly` | Set `true` if ability is informational only |
+
+## Recommended patterns
+
+- Namespace IDs (e.g. `my-plugin:feature.edit`).
+- Treat IDs as stable API; changing IDs is a breaking change.
+- Use `input_schema` and `output_schema` for validation and to help AI agents understand usage.
+- Always include a `permission_callback` for abilities that modify data.
+
+## References
+
+- Abilities API handbook: https://developer.wordpress.org/apis/abilities-api/
+- Dev note: https://make.wordpress.org/core/2025/11/10/abilities-api-in-wordpress-6-9/
+

package/skills/wp-abilities-api/references/rest-api.md

@@ -0,0 +1,13 @@
+# REST API quick guide (`wp-abilities/v1`)
+
+The Abilities API exposes endpoints under the REST namespace:
+
+- `wp-abilities/v1/abilities`
+- `wp-abilities/v1/categories`
+
+Debug checklist:
+
+- Confirm the route exists under `wp-json/wp-abilities/v1/...`.
+- Verify the ability/category shows in REST responses.
+- If missing, confirm `meta.show_in_rest` is enabled for that ability.
+