wp_register_ability() Function: How It Works [Guide]

Abilities let plugins, the REST API, and AI tools discover and run functionality on your site. wp_register_ability() is how you declare one.

Registration takes a namespaced name, a settings array, and callbacks. This guide covers each part, the hook it must run on, and the mistakes that make registration fail.

What the Function Does

wp_register_ability() registers an ability with the Abilities API. Once registered, other plugins, the REST API, MCP clients, and AI agents can find and run it, as long as its settings allow access. It was introduced in WordPress 6.9.0.

Naming and Category Rules

• Namespace. The name needs a prefix before a slash, such as my-plugin/analyze-sentiment.
• Characters. Use lowercase letters, numbers, dashes, and slashes only.
• Action style. Name the ability for the action it performs, such as analyze-sentiment.
• Category. Abilities must belong to a category, and the category must be registered first. See wp_register_ability_category().

Parameters and Return Value

The function takes two arguments.

The $name Parameter

The namespaced identifier described above. Each ability name must be unique.

The $args Array

The settings array. label, description, and category describe the ability. execute_callback and permission_callback run it. input_schema and output_schema validate data. meta holds flags such as public and show_in_rest.

On success, the function returns a WP_Ability object. It returns null if registration fails, for example when called at the wrong time, given an invalid configuration, or when the ability already exists.

Schemas and Callbacks

Input and Output Schemas

Schemas use JSON Schema to validate what an ability receives and returns. The validator supports a subset of Draft 4. Schemas are required whenever a value is passed in or returned.

Execute and Permission Callbacks

The execute callback does the work and returns a result or a WP_Error. The permission callback decides whether the call may run and returns a boolean or a WP_Error. A common check is a capability test:

<?php

function my_can_analyze_sentiment() {
    return current_user_can( 'edit_posts' );
}

Registering an Ability

Register abilities on the wp_abilities_api_init hook, the same way you would attach any action with add_action(). The example below assumes the text-processing category is already registered and that the callbacks exist.

<?php

add_action( 'wp_abilities_api_init', 'my_register_sentiment_ability' );

function my_register_sentiment_ability() {
    wp_register_ability(
        'my-plugin/analyze-sentiment',
        array(
            'label'               => __( 'Analyze Sentiment', 'my-plugin' ),
            'description'         => __( 'Returns the sentiment of a text.', 'my-plugin' ),
            'category'            => 'text-processing',
            'input_schema'        => array(
                'type'       => 'object',
                'properties' => array(
                    'text' => array( 'type' => 'string', 'minLength' => 1 ),
                ),
                'required'   => array( 'text' ),
            ),
            'output_schema'       => array(
                'type'       => 'object',
                'properties' => array(
                    'sentiment' => array( 'type' => 'string', 'enum' => array( 'positive', 'negative', 'neutral' ) ),
                ),
            ),
            'execute_callback'    => 'my_analyze_sentiment',
            'permission_callback' => 'my_can_analyze_sentiment',
        )
    );
}

Making an Ability Public

The public flag makes an ability available to clients such as the REST API, MCP, and AI agents. It sets the default for per-channel flags like show_in_rest, which you can override. Add it to the meta array:

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

Set show_in_rest to false to keep a public ability out of the REST API. For the REST side of things, see register_rest_route().

Common Mistakes

• Wrong hook. Calling the function outside wp_abilities_api_init returns null and triggers a doing-it-wrong notice.
• Unregistered category. Referencing a category you have not registered yet.
• Duplicate names. Registering a name that already exists returns null.
• Missing schemas. Leaving out a schema for a value the ability takes or returns.

FAQs About wp_register_ability

Which WordPress Version Added It?

It was introduced in WordPress 6.9.0.

What Does It Return?

A WP_Ability object on success, or null on failure.

Do I Need to Register a Category?

Yes. Categories must be registered before any ability that uses them. See wp_register_ability_category().

What Happens on the Wrong Hook?

The function returns null and triggers a doing-it-wrong notice. Move the call into a callback on wp_abilities_api_init.

Conclusion

wp_register_ability() needs a namespaced name, a settings array, and the right hook. Get those right, and other plugins, the REST API, and AI tools can discover and run your abilities.

Need abilities built for your site? Hire a WordPress developer, or reach out to me directly.