Description

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,
                ),
                'show_in_rest' => 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' );
}

REST API Integration

Abilities can be exposed through the REST API by setting show_in_rest to true in the meta configuration:

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

This allows abilities to be invoked via HTTP requests to the WordPress REST API.

See also

• WP_Abilities_Registry::register()
• wp_register_ability_category()
• wp_unregister_ability()