Agent Skills for WordPress

https://github.com/wordpress/agent-skills
Admin
Agent Skills are portable bundles of instructions and best practices that teach AI coding assistants...
Tokens:50,934
Snippets:452
Trust Score:9.1
Update:8 months ago
Show doc for...
Tokens:
Raw
### Minimal WordPress Blueprint Setup (JSON)

Source: https://github.com/wordpress/agent-skills/blob/trunk/skills/wp-playground/references/blueprints.md

This JSON blueprint demonstrates a minimal setup for WordPress, including installing a theme and a plugin. It utilizes the `$schema` for validation and defines a list of `steps` to be executed by the Playground.

```json
{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "steps": [
    { "step": "installTheme", "themeZipUrl": "https://downloads.wordpress.org/theme/twentytwentythree.zip" },
    { "step": "installPlugin", "pluginZipUrl": "https://downloads.wordpress.org/plugin/classic-editor.zip" }
  ]
}
```

--------------------------------

### Inspect WP-CLI Setup with Node.js Script (Bash)

Source: https://context7.com/wordpress/agent-skills/llms.txt

Inspects the WP-CLI setup and site configuration using a Node.js script. This is useful for diagnosing operational issues and verifying the environment. The script requires the path to the WordPress installation and can optionally specify a URL for multisite configurations.

```bash
# Inspect WP-CLI setup
node skills/wp-wpcli-and-ops/scripts/wpcli_inspect.mjs --path=/var/www/html

# For multisite
node skills/wp-wpcli-and-ops/scripts/wpcli_inspect.mjs --path=/var/www/html --url=https://mysite.com
```

--------------------------------

### Start WordPress Playground Server (Bash)

Source: https://context7.com/wordpress/agent-skills/llms.txt

Spins up a disposable WordPress local development environment with auto-mounted plugin or theme code. This tool allows for quick setup and testing of WordPress instances. You can specify WordPress and PHP versions, custom ports, and enable Xdebug for debugging.

```bash
# Start Playground with auto-mounted plugin/theme
cd my-wordpress-plugin
npx @wp-playground/cli@latest server --auto-mount

# Specify WordPress and PHP versions
npx @wp-playground/cli@latest server --auto-mount --wp=6.9 --php=8.3

# Custom port
npx @wp-playground/cli@latest server --auto-mount --port=8080

# Enable Xdebug for debugging
npx @wp-playground/cli@latest server --auto-mount --xdebug
```

--------------------------------

### Registering Custom REST API Endpoints in WordPress

Source: https://context7.com/wordpress/agent-skills/llms.txt

Demonstrates how to register custom REST API endpoints in WordPress using the `rest_api_init` action. It includes examples for both readable (GET) and creatable (POST) methods, with argument validation, sanitization, and permission callbacks.

```php
<?php
add_action( 'rest_api_init', function() {
    register_rest_route( 'my-plugin/v1', '/items', array(
        array(
            'methods'             => WP_REST_Server::READABLE,
            'callback'            => 'get_items_handler',
            'permission_callback' => '__return_true', // Public endpoint
            'args'                => array(
                'per_page' => array(
                    'type'              => 'integer',
                    'default'           => 10,
                    'minimum'           => 1,
                    'maximum'           => 100,
                    'sanitize_callback' => 'absint',
                ),
                'category' => array(
                    'type'              => 'string',
                    'sanitize_callback' => 'sanitize_text_field',
                    'validate_callback' => function( $param ) {
                        return in_array( $param, array( 'news', 'events', 'updates' ), true );
                    },
                ),
            ),
        ),
        array(
            'methods'             => WP_REST_Server::CREATABLE,
            'callback'            => 'create_item_handler',
            'permission_callback' => function( $request ) {
                return current_user_can( 'edit_posts' );
            },
            'args'                => array(
                'title' => array(
                    'type'              => 'string',
                    'required'          => true,
                    'sanitize_callback' => 'sanitize_text_field',
                ),
                'content' => array(
                    'type'              => 'string',
                    'sanitize_callback' => 'wp_kses_post',
                ),
            ),
        ),
    ) );
} );

function get_items_handler( WP_REST_Request $request ) {
    $per_page = $request->get_param( 'per_page' );
    $category = $request->get_param( 'category' );

    // Query items...
    $items = array( /* ... */ );

    return rest_ensure_response( $items );
}

function create_item_handler( WP_REST_Request $request ) {
    $title   = $request->get_param( 'title' );
    $content = $request->get_param( 'content' );

    // Create item...
    $item_id = wp_insert_post( array(
        'post_title'   => $title,
        'post_content' => $content,
        'post_status'  => 'publish',
        'post_type'    => 'my_item',
    ) );

    if ( is_wp_error( $item_id ) ) {
        return new WP_Error( 'create_failed', 'Could not create item', array( 'status' => 500 ) );
    }

    return rest_ensure_response( array(
        'id'      => $item_id,
        'title'   => $title,
        'message' => 'Item created successfully',
    ) );
}

```

--------------------------------

### Install Agent Skills Globally for Claude Code

Source: https://github.com/wordpress/agent-skills/blob/trunk/README.md

This command sequence clones the agent-skills repository, builds the distribution, and installs all skills globally, making them available for Claude Code across all projects. It installs skills to `~/.claude/skills/`.

```bash
git clone https://github.com/WordPress/agent-skills.git
cd agent-skills
node shared/scripts/skillpack-build.mjs --clean
node shared/scripts/skillpack-install.mjs --global
```

--------------------------------

### Install Skillpack into Another Repository using Node.js

Source: https://github.com/wordpress/agent-skills/blob/trunk/docs/packaging.md

Installs the built agent skills distribution into a specified destination repository. The `--targets` argument allows selection of specific distribution formats (e.g., codex, vscode, claude, cursor). The default installation mode is 'replace'.

```bash
node shared/scripts/skillpack-install.mjs --dest=../some-repo --targets=codex,vscode,claude,cursor
```

--------------------------------

### Install Agent Skills Globally for Cursor

Source: https://github.com/wordpress/agent-skills/blob/trunk/README.md

This command installs agent skills globally for Cursor, making them available in `~/.cursor/skills/` where Cursor will automatically discover and utilize them for project-level assistance.

```bash
node shared/scripts/skillpack-install.mjs --targets=cursor-global
```

--------------------------------

### List Available Agent Skills

Source: https://github.com/wordpress/agent-skills/blob/trunk/README.md

This command lists all available agent skills that can be installed, either globally or into a specific project. It's a useful command for understanding the full scope of available skills before installation.

```bash
node shared/scripts/skillpack-install.mjs --list
```

--------------------------------

### Build WordPress Playground Snapshot (Bash)

Source: https://context7.com/wordpress/agent-skills/llms.txt

Creates a portable ZIP snapshot of a WordPress Playground instance. This is useful for sharing a specific WordPress setup or for creating reproducible environments. The snapshot can be built from a blueprint file and saved to a specified output file.

```bash
# Build a snapshot from a blueprint
npx @wp-playground/cli@latest build-snapshot --blueprint=./setup.json --outfile=./site-snapshot.zip
```

--------------------------------

### Complete Example: List Rendering with Client Logic (JavaScript)

Source: https://github.com/wordpress/agent-skills/blob/trunk/skills/wp-interactivity-api/references/server-side-rendering.md

This JavaScript code defines the client-side logic for the fruit list example using the Interactivity API. It sets up the store for 'myFruitPlugin', including a computed property `hasFruits` and actions `addMango` and `clearAll` to manage the fruit list state.

```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 = [];
    },
  },
});
```

--------------------------------

### Register Ability Category and Ability in PHP

Source: https://github.com/wordpress/agent-skills/blob/trunk/skills/wp-abilities-api/references/php-registration.md

Registers a new ability category and then registers an ability within that category using WordPress hooks. Ensure categories are registered before abilities using `wp_abilities_api_categories_init` and `wp_abilities_api_init` respectively. This example demonstrates basic registration with a label, description, category, and REST API exposure.

```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 ],
    ] );
} );
```

--------------------------------

### Install Specific Agent Skills Globally for Claude Code

Source: https://github.com/wordpress/agent-skills/blob/trunk/README.md

This command clones the agent-skills repository, builds the distribution, and installs only the specified skills globally for Claude Code. This is useful for managing a smaller set of frequently used skills.

```bash
git clone https://github.com/WordPress/agent-skills.git
cd agent-skills
node shared/scripts/skillpack-build.mjs --clean
node shared/scripts/skillpack-install.mjs --global --skills=wp-playground,wp-block-development
```

--------------------------------

### Quick Local WordPress Spin-up with Auto-Mount

Source: https://github.com/wordpress/agent-skills/blob/trunk/skills/wp-playground/SKILL.md

This command spins up a local WordPress instance, automatically detecting and mounting the current directory's plugin or theme. It's useful for quickly testing code without a full setup. Dependencies include Node.js and npm/npx.

```bash
cd <plugin-or-theme-root>
npx @wp-playground/cli@latest server --auto-mount
```

--------------------------------

### Run WordPress Playground Blueprint (Bash)

Source: https://context7.com/wordpress/agent-skills/llms.txt

Executes a WordPress Playground blueprint for scripted setup and CI validation. Blueprints define the desired state of a WordPress environment, allowing for automated configuration and testing. This command can run local or remote blueprint files and optionally allow local file access.

```bash
# Run a local blueprint file
npx @wp-playground/cli@latest run-blueprint --blueprint=./test-blueprint.json

# Run a remote blueprint
npx @wp-playground/cli@latest run-blueprint --blueprint=https://example.com/blueprint.json

# Allow local file access in blueprints
npx @wp-playground/cli@latest run-blueprint --blueprint=./blueprint.json --blueprint-may-read-adjacent-files
```

--------------------------------

### Dry Run Agent Skills Installation

Source: https://github.com/wordpress/agent-skills/blob/trunk/README.md

This command performs a dry run of the global agent skills installation process. It previews which skills would be installed without actually modifying any files, allowing for review before committing to an installation.

```bash
node shared/scripts/skillpack-install.mjs --global --dry-run
```

--------------------------------

### Install Specific Agent Skills to a Project

Source: https://github.com/wordpress/agent-skills/blob/trunk/README.md

This command installs specific agent skills, such as `wp-wpcli-and-ops`, into a project directory and targets specific AI assistants like Claude and Cursor. This allows for fine-grained control over which skills are available for different projects and AI tools.

```bash
node shared/scripts/skillpack-install.mjs --dest=../my-repo --targets=claude,cursor --skills=wp-wpcli-and-ops
```

--------------------------------

### Complete Example: List Rendering with Server State (PHP)

Source: https://github.com/wordpress/agent-skills/blob/trunk/skills/wp-interactivity-api/references/server-side-rendering.md

This PHP code serves as the server-side rendering part for a fruit list example using the Interactivity API. It initializes state including fruits, a flag for their availability, and a label for 'Mango'. It then renders HTML with interactive buttons and a list that conditionally displays based on the `hasFruits` state.

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

--------------------------------

### Manage WordPress Themes with WP-CLI

Source: https://github.com/wordpress/agent-skills/blob/trunk/skills/wp-wpcli-and-ops/SKILL.md

Illustrates managing WordPress themes via WP-CLI. This covers installing, activating, updating, and deleting themes. Similar to plugin management, it's important to verify the target site and network, particularly for multisite installations.

```bash
wp theme install <theme-name>
wp theme activate <theme-name>
wp theme update <theme-name>
wp theme delete <theme-name>
```

--------------------------------

### Backend Performance Inspection with Node.js Script (Bash)

Source: https://context7.com/wordpress/agent-skills/llms.txt

Generates a backend performance report without requiring browser access, using a Node.js script. This tool helps in identifying performance bottlenecks on the server-side. It requires the path to the WordPress installation and can be configured for multisite environments by specifying the URL.

```bash
# Run performance inspection
node skills/wp-performance/scripts/perf_inspect.mjs --path=/var/www/html

# For multisite
node skills/wp-performance/scripts/perf_inspect.mjs --path=/var/www/html --url=https://mysite.com
```

--------------------------------

### Running a WordPress Playground Blueprint

Source: https://github.com/wordpress/agent-skills/blob/trunk/skills/wp-playground/SKILL.md

Executes a WordPress Playground Blueprint, which defines a setup or workflow. This is ideal for scripted setups and CI validation. It can use local files or remote URLs for blueprints. Ensure the blueprint file or URL is accessible.

```bash
npx @wp-playground/cli@latest run-blueprint --blueprint=<file-or-url>
```

--------------------------------

### Install Agent Skills into a WordPress Project Repository

Source: https://github.com/wordpress/agent-skills/blob/trunk/README.md

This command sequence clones the agent-skills repository, builds the distribution, and installs the skills into a specified destination directory within your WordPress project. It targets multiple AI assistants including Codex, VS Code/Copilot, Claude Code, and Cursor.

```bash
git clone https://github.com/WordPress/agent-skills.git
cd agent-skills
node shared/scripts/skillpack-build.mjs --clean
node shared/scripts/skillpack-install.mjs --dest=../your-wp-project --targets=codex,vscode,claude,cursor
```

--------------------------------

### Build Skillpack Distribution using Node.js

Source: https://github.com/wordpress/agent-skills/blob/trunk/docs/packaging.md

Builds a packaged copy of the agent skills distribution under the `dist/` directory. This command prepares the skills for distribution to various target repositories like OpenAI Codex, VS Code/Copilot, Claude, and Cursor.

```bash
node shared/scripts/skillpack-build.mjs --clean
```

--------------------------------

### Server-Side Rendering with Interactivity API State in WordPress

Source: https://context7.com/wordpress/agent-skills/llms.txt

Initializes the WordPress Interactivity API state on the server-side using PHP for proper hydration of dynamic components. This example demonstrates setting up state variables and using them within HTML attributes for client-side interactivity.

```php
<?php
// In render.php or render callback
wp_interactivity_state( 'myPlugin', array(
    'items'      => array( 'Apple', 'Banana', 'Cherry' ),
    'isExpanded' => false,
    'hasItems'   => function() {
        $state = wp_interactivity_state();
        return count( $state['items'] ) > 0;
    },
) );

$context = array( 'currentIndex' => 0 );
?>
<div
    <?php echo get_block_wrapper_attributes(); ?>
    data-wp-interactive="myPlugin"
    <?php echo wp_interactivity_data_wp_context( $context ); ?>
>
    <button
        data-wp-on--click="actions.toggleExpanded"
        data-wp-bind--aria-expanded="state.isExpanded"
    >
        Toggle Items
    </button>

    <ul data-wp-bind--hidden="!state.isExpanded">
        <template data-wp-each="state.items">
            <li data-wp-text="context.item"></li>
        </template>
    </ul>
</div>

```

--------------------------------

### Perform Safe Search-Replace with WP-CLI

Source: https://github.com/wordpress/agent-skills/blob/trunk/skills/wp-wpcli-and-ops/SKILL.md

Guides through a safe sequence for URL and domain migrations using `wp search-replace`. It includes backing up the database, performing a dry run to review changes, executing the actual replacement, and flushing caches if necessary. This is crucial for preventing data corruption during migrations.

```bash
wp db export
wp search-replace --dry-run
wp search-replace <old_url> <new_url> --all-tables
wp cache flush
wp rewrite flush
```

--------------------------------

### Manage WordPress Plugins with WP-CLI

Source: https://github.com/wordpress/agent-skills/blob/trunk/skills/wp-wpcli-and-ops/SKILL.md

Demonstrates how to manage WordPress plugins using WP-CLI commands. This includes installing, activating, updating, and deactivating plugins. It emphasizes confirming the correct site and network context before executing commands, especially in multisite environments.

```bash
wp plugin install <plugin-name>
wp plugin activate <plugin-name>
wp plugin update <plugin-name>
wp plugin deactivate <plugin-name>
```

--------------------------------

### Serialized Output for Fruit List Example (HTML)

Source: https://github.com/wordpress/agent-skills/blob/trunk/skills/wp-interactivity-api/references/server-side-rendering.md

This HTML represents the initial rendered output for the fruit list example, generated server-side. It includes the interactive elements and the list of fruits. The `hidden` attribute is correctly applied to the 'No fruits available' paragraph because `state.hasFruits` was true during server rendering.

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

--------------------------------

### Safe URL Migration with WP-CLI Search-Replace (Bash)

Source: https://context7.com/wordpress/agent-skills/llms.txt

Performs database search-replace operations for URL migration with proper safety measures using WP-CLI. This process involves exporting a database backup, performing a dry run to preview changes, executing the replacement, and flushing caches. For multisite installations, the `--url` parameter must always be specified.

```bash
# Step 1: Create a backup
wp db export backup-before-migration.sql --path=/var/www/html

# Step 2: Dry run to preview changes
wp search-replace 'https://old-domain.com' 'https://new-domain.com' --dry-run --path=/var/www/html

# Step 3: Execute the replacement
wp search-replace 'https://old-domain.com' 'https://new-domain.com' --path=/var/www/html

# Step 4: Flush caches
wp cache flush --path=/var/www/html
wp rewrite flush --path=/var/www/html

# For multisite, always specify --url
wp search-replace 'https://old.com' 'https://new.com' --url=https://subsite.old.com --path=/var/www/html
```

--------------------------------

### Server-Side Rendering with State

Source: https://context7.com/wordpress/agent-skills/llms.txt

Demonstrates how to initialize the Interactivity API state in PHP for server-side rendering and client-side hydration. This pattern allows dynamic content and interactivity to be managed from the server.

```APIDOC
## Interactivity API: Server-Side Rendering with State

### Description
This pattern initializes the WordPress Interactivity API state on the server-side, ensuring that dynamic content and interactive elements are properly hydrated on the client. It's typically used within a block's `render.php` file or a custom render callback.

### Method
Server-Side Rendering (PHP)

### Endpoint
N/A (This is a pattern for rendering dynamic blocks/components)

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (Rendered HTML)
- The rendered HTML output includes `data-wp-interactive` attributes and `wp_interactivity_state()` calls to manage client-side state.

#### Response Example (HTML Snippet)
```html
<div data-wp-interactive="myPlugin" data-wp-context='{"currentIndex":0}'>
    <button data-wp-on--click="actions.toggleExpanded" data-wp-bind--aria-expanded="state.isExpanded">
        Toggle Items
    </button>

    <ul data-wp-bind--hidden="!state.isExpanded">
        <template data-wp-each="state.items">
            <li data-wp-text="context.item"></li>
        </template>
    </ul>
</div>
```

### PHP Initialization Example
```php
<?php
// In render.php or render callback
wp_interactivity_state( 'myPlugin', array(
    'items'      => array( 'Apple', 'Banana', 'Cherry' ),
    'isExpanded' => false,
    'hasItems'   => function() {
        $state = wp_interactivity_state();
        return count( $state['items'] ) > 0;
    },
) );

$context = array( 'currentIndex' => 0 );
?>
```
```

--------------------------------

### Directive Separator Example (HTML)

Source: https://github.com/wordpress/agent-skills/blob/trunk/skills/wp-interactivity-api/SKILL.md

This HTML example demonstrates the use of unique directive IDs in WordPress 6.9+, allowing multiple directives of the same type on a single element using the `---` separator. This improves flexibility and avoids conflicts between different plugins or features. It requires WordPress 6.9+.

```html
<button 
  data-wp-on--click---plugin-a="doSomethingA()" 
  data-wp-on--click---plugin-b="doSomethingB()">
  Click Me
</button>
```

--------------------------------

### Building a WordPress Playground Snapshot

Source: https://github.com/wordpress/agent-skills/blob/trunk/skills/wp-playground/SKILL.md

Creates a reproducible snapshot (ZIP archive) of a WordPress site based on a blueprint. This snapshot can be shared or used in CI processes. The output is a ZIP file that can be loaded into Playground or attached to bug reports.

```bash
npx @wp-playground/cli@latest build-snapshot --blueprint=<file> --outfile=./site.zip
```

--------------------------------

### Install WordPress Stub Packages with Composer

Source: https://github.com/wordpress/agent-skills/blob/trunk/skills/wp-phpstan/references/third-party-classes.md

This command installs development dependencies for PHPStan to provide stubs for WordPress and popular plugins like WooCommerce and Advanced Custom Fields Pro. These stubs help PHPStan understand the APIs of these external libraries, improving type checking accuracy.

```bash
composer require --dev szepeviktor/phpstan-wordpress
composer require --dev php-stubs/wordpress-stubs
composer require --dev php-stubs/woocommerce-stubs
composer require --dev php-stubs/acf-pro-stubs
```

--------------------------------

### Register WordPress Activation Hook

Source: https://github.com/wordpress/agent-skills/blob/trunk/skills/wp-plugin-development/references/lifecycle.md

Registers a callback function to be executed when the plugin is activated. This is useful for one-time setup tasks. Ensure the hook is registered at the top level of your plugin file.

```php
register_activation_hook( __FILE__, 'your_activation_callback' );
```

--------------------------------

### Registering Ability Categories and Abilities

Source: https://github.com/wordpress/agent-skills/blob/trunk/skills/wp-abilities-api/references/php-registration.md

This section details the process of registering ability categories and abilities using the WordPress Abilities API. It highlights the critical hook order: categories must be registered before abilities.

```APIDOC
## Registering Ability Categories and Abilities

### Description
Register ability categories and abilities in PHP using the WordPress Abilities API. Ensure categories are registered before abilities by using the correct init hooks.

### Method
PHP Functions (add_action)

### Endpoint
N/A (Server-side registration)

### Parameters

#### `wp_register_ability_category( $category_id, $args )`

- **`$category_id`** (string) - Required - A unique identifier for the category. Recommended to namespace (e.g., 'my-plugin').
- **`$args`** (array) - Required - An array of arguments for the category.
  - **`label`** (string) - Required - Human-readable name for the category.

#### `wp_register_ability( $ability_id, $args )`

- **`$ability_id`** (string) - Required - A unique identifier for the ability. Recommended to namespace (e.g., 'my-plugin/feature.edit').
- **`$args`** (array) - Required - An array of arguments for the ability.
  - **`label`** (string) - Required - Human-readable name for the ability.
  - **`description`** (string) - Optional - A description of what the ability does.
  - **`category`** (string) - Required - The ID of the category this ability belongs to. Must be registered first.
  - **`callback`** (callable) - Required - The PHP function that executes the ability.
  - **`input_schema`** (object) - Optional - JSON Schema defining the expected input for the ability.
  - **`output_schema`** (object) - Optional - JSON Schema defining the output of the ability.
  - **`permission_callback`** (callable) - Optional - A function to check if the current user can execute the ability.
  - **`meta`** (array) - Optional - An array of meta information.
    - **`show_in_rest`** (boolean) - Optional - Set to `true` to expose the ability via the REST API.
    - **`readonly`** (boolean) - Optional - Set to `true` if the ability is informational only.

### Hook Order

1.  **`wp_abilities_api_categories_init`**: Register categories here.
2.  **`wp_abilities_api_init`**: Register abilities here (after categories exist).

**Warning:** Registering abilities outside `wp_abilities_api_init` will trigger `_doing_it_wrong()` and the registration will fail.

### Request Example

```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 ],
    ] );
} );
```

### Response

#### Success Response (N/A - Server-side registration)

Abilities and categories are registered on the server. Success is indicated by the absence of errors during the hook execution.

#### Response Example

N/A
```

--------------------------------

### Profile WordPress Performance with WP-CLI (Bash)

Source: https://context7.com/wordpress/agent-skills/llms.txt

Profiles WordPress performance using WP-CLI's built-in profile command. This allows for detailed analysis of various stages, including bootstrap, main query, and template rendering. It can also profile specific hooks, code paths, or run doctor checks for common issues.

```bash
# Profile bootstrap stages
wp profile stage --path=/var/www/html
# Output shows time spent in: bootstrap, main_query, template

# Profile specific hooks
wp profile hook --url=https://mysite.com/slow-page/ --path=/var/www/html

# Profile a specific code path
wp profile eval 'get_option("siteurl");' --path=/var/www/html

# Run doctor checks for common issues
wp doctor check --path=/var/www/html
```

--------------------------------

### Run Evaluation Harness (Node.js)

Source: https://github.com/wordpress/agent-skills/blob/trunk/docs/upstream-sync.md

This command executes the evaluation harness using Node.js, which is a crucial step for validating changes within the project. It ensures that the implemented logic functions as expected.

```bash
node eval/harness/run.mjs
```
Tokens:
Raw