wp_register_ability( string $name, array $args ): WP_Ability|null

1. Hook into the wp_abilities_api_init action.
2. Call wp_register_ability() with a namespaced name and configuration.
3. Provide execute and permission callbacks.

Example:

function my_plugin_register_abilities(): void {
 wp_register_ability(
 'my-plugin/analyze-text',
 array(
 'label' => __( 'Analyze Text', 'my-plugin' ),
 'description' => __( 'Performs sentiment analysis on provided text.', 'my-plugin' ),
 'category' => 'text-processing',
 'input_schema' => array(
 'type' => 'string',
 'description' => __( 'The text to be analyzed.', 'my-plugin' ),
 'minLength' => 10,
 'required' => true,
 ),
 'output_schema' => array(
 'type' => 'string',
 'enum' => array( 'positive', 'negative', 'neutral' ),
 'description' => __( 'The sentiment result: positive, negative, or neutral.', 'my-plugin' ),
 'required' => true,
 ),
 'execute_callback' => 'my_plugin_analyze_text',
 'permission_callback' => 'my_plugin_can_analyze_text',
 'meta' => array(
 'annotations' => array(
 'readonly' => true,
 ),
 'public' => true,
 ),
 )
 );
}
add_action( 'wp_abilities_api_init', 'my_plugin_register_abilities' );

Naming Conventions

Ability names must follow these rules:

• Include a namespace prefix (e.g., my-plugin/my-ability).
• Use only lowercase alphanumeric characters, dashes, and forward slashes.
• Use descriptive, action-oriented names (e.g., process-payment, generate-report).

Categories

Abilities must be organized into categories. Ability categories provide better discoverability and must be registered before the abilities that reference them:

function my_plugin_register_categories(): void {
 wp_register_ability_category(
 'text-processing',
 array(
 'label' => __( 'Text Processing', 'my-plugin' ),
 'description' => __( 'Abilities for analyzing and transforming text.', 'my-plugin' ),
 )
 );
}
add_action( 'wp_abilities_api_categories_init', 'my_plugin_register_categories' );

Input and Output Schemas

Schemas define the expected structure, type, and constraints for ability inputs and outputs using JSON Schema syntax. They serve two critical purposes: automatic validation of data passed to and returned from abilities, and self-documenting API contracts for developers.

WordPress implements a validator based on a subset of the JSON Schema Version 4 specification (https://json-schema.org/specification-links.html#draft-4).
For details on supported JSON Schema properties and syntax, see the related WordPress REST API Schema documentation: https://developer.wordpress.org/rest-api/extending-the-rest-api/schema/#json-schema-basics

Defining schemas is mandatory when there is a value to pass or return.
They ensure data integrity, improve developer experience, and enable better documentation:

'input_schema' => array(
 'type' => 'string',
 'description' => __( 'The text to be analyzed.', 'my-plugin' ),
 'minLength' => 10,
 'required' => true,
),
'output_schema' => array(
 'type' => 'string',
 'enum' => array( 'positive', 'negative', 'neutral' ),
 'description' => __( 'The sentiment result: positive, negative, or neutral.', 'my-plugin' ),
 'required' => true,
),

Callbacks

Execute Callback

The execute callback performs the ability's core functionality. It receives optional input data and returns either a result or WP_Error on failure.

function my_plugin_analyze_text( string $input ): string|WP_Error {
 $score = My_Plugin::perform_sentiment_analysis( $input );
 if ( is_wp_error( $score ) ) {
 return $score;
 }
 return My_Plugin::interpret_sentiment_score( $score );
}

Permission Callback

The permission callback determines whether the ability can be executed.
It receives the same input as the execute callback and must return a boolean or WP_Error. Common use cases include checking user capabilities, validating API keys, or verifying system state:

function my_plugin_can_analyze_text( string $input ): bool|WP_Error {
 return current_user_can( 'edit_posts' );
}

Client Exposure

Set the high-level public flag to make an ability available to clients such as the REST API, MCP, or AI agents:

'meta' => array(
 'public' => true,
),

The public flag seeds the default for each per-channel flag. For the REST API it seeds show_in_rest, which lets the ability be invoked via HTTP requests. Set a per-channel flag directly to override that default. For example, keep a public ability out of the REST API:

'meta' => array(
 'public' => true,
 'show_in_rest' => false,
),