Getting started with the WordPress Abilities API: A practical guide

Introduced in WordPress, the Abilities API establishes a shared language, allowing all WordPress components—both core and plugins—to expose their functionality in a unified, understandable way for humans and machines alike. This architecture makes a WordPress site ready for integration with external automation tools in a standardized and secure manner.

Consider use cases such as an AI model guiding a user through an e-commerce purchasing process directly, or a CI/CD pipeline on GitHub Actions processing text extracted from an audio file and sending it to WordPress for publication. The Abilities API changes the role of WordPress from a traditional content management system into a distributed execution engine capable of being orchestrated from the outside.

What an ability is intended for

An ability is a discoverable, actionable capability on a WordPress site that enables specific operations for external entities (such as AI models) or internal components. Typical operations include searching for content, reading site configuration settings, creating posts, or converting a JSON structure into Gutenberg blocks.

Exposing an ability means making a specific functionality interoperable. Before an ability can be discovered and used, it must be registered in a centralized catalog. Only then can WordPress and AI models discover it, understand its intent, and invoke it. By default, plugin functionalities are fully isolated; registering an ability declares that the underlying logic is available as a service for the entire ecosystem.

Working with the Abilities API

The Abilities API provides a comprehensive set of functions allowing developers to discover registered abilities, activate them, and register or unregister them as needed. You can retrieve a list of all registered abilities or fetch individual ability objects using dedicated PHP functions combined with WP-CLI.

To view all registered abilities on your site, execute a simple WP-CLI evaluation command in your terminal:

wp eval '$abilities = wp_get_abilities(); foreach ( $abilities as $a ) { echo $a->get_name() . PHP_EOL; }'

By default, this command returns core abilities such as core/get-site-info, core/get-user-info, and core/get-environment-info.

Inspecting ability metadata and schemas

Every ability acts as a formal contract specifying input expectations, intent, and output data schemas. You can query an individual ability object using wp_get_ability() to inspect its structural definition, including input and output schemas and execution metadata.

wp eval ' $ability = wp_get_ability( "core/get-site-info" ); if ( $ability ) { var_dump( $ability->get_input_schema() ); } '

This introspection ensures that calling entities know precisely what data types, required fields, and structural constraints are enforced before execution.

Checking registration and permissions

Before triggering execution, applications often need to verify availability and authorization. The wp_has_ability() function checks whether a target ability exists within the registry.

Additionally, you can evaluate runtime authorization using the check_permissions() method on the ability object:

wp --user=1 eval ' $ability = wp_get_ability( "core/get-site-info" ); if ( $ability ) { $has_permissions = $ability->check_permissions(); var_dump( $has_permissions ); } '

This returns true, false, or a WP_Error object depending on whether the current context satisfies the requirement.

Registering a custom ability category

To add custom capabilities, you must first register an ability category by hooking into wp_abilities_api_categories_init. The registration function accepts a unique category slug and an array of metadata.

function aicb_register_ability_category(): void {
    if ( ! function_exists( 'wp_register_ability_category' ) ) {
        return;
    }
    wp_register_ability_category( 'content-generation', array(
        'label' => 'Content Generation',
        'description' => 'AI-powered content transformation and structuring abilities',
    ) );
}
add_action( 'wp_abilities_api_categories_init', 'aicb_register_ability_category' );

Defining schemas and execution callbacks

Once the category is active, you register the ability via the wp_abilities_api_init action using wp_register_ability(). You must supply input schemas, output schemas, an execution callback, and a permission callback.

function aicb_register_audio_to_gutenberg_blocks_ability(): void {
    if ( ! function_exists( 'wp_register_ability' ) ) {
        return;
    }
    wp_register_ability( 'ai-content-builder/audio-to-gutenberg-blocks', array(
        'category' => 'content-generation',
        'label' => 'Audio to Gutenberg Blocks',
        'description' => 'Transcribes audio and converts content into Gutenberg blocks.',
        'input_schema' => array(
            'type' => 'object',
            'properties' => array(
                'audio_id' => array(
                    'type' => 'integer',
                    'description' => 'The ID of the audio attachment to process.',
                ),
            ),
            'required' => array( 'audio_id' ),
        ),
        'output_schema' => array(
            'type' => 'object',
            'properties' => array(
                'blocks' => array(
                    'type' => 'array',
                    'items' => array( 'type' => 'object' ),
                ),
            ),
            'required' => array( 'blocks' ),
        ),
        'execute_callback' => 'aicb_audio_to_gutenberg_blocks_callback',
        'permission_callback' => static function (): bool {
            return current_user_can( 'edit_posts' );
        },
    ) );
}
add_action( 'wp_abilities_api_init', 'aicb_register_audio_to_gutenberg_blocks_ability' );

Executing an ability programmatically

Once registered, execution occurs via the execute() method on the retrieved ability instance. WordPress validates incoming payloads against your defined input schema before passing control to your custom callback function.

wp --user=1 eval ' $ability = wp_get_ability( "core/get-site-info" ); if ( $ability ) { $result = $ability->execute(); echo json_encode( $result ); } '

Primary reference: Review the original announcement for exact release details. This article is an independent explanation and does not reproduce the source text.