wp_register_ability() │ WP 6.9.0

Registers a new ability in the Abilities API.

An ability describes one operation: its input, output, execution callback, and access rules. Registered abilities can be discovered and run by other plugins, the REST API, MCP, and AI tools.

To register an ability:

1. Hook into wp_abilities_api_init.
2. Pass the ability name and settings to wp_register_ability().
3. Provide permission and execution callbacks.

The ability name must:

• Include a namespace, for example my-plugin/generate-report.
• Use lowercase Latin letters, numbers, hyphens, and /.
• Describe an action, such as process-payment, rather than just payment.

Input and output are described with JSON Schema. WordPress validates the data passed to the ability and the result it returns against these schemas.

A schema is required when the ability accepts or returns a value. The supported format is a subset of JSON Schema Draft 4.

No Hooks.

Returns

WP_Ability|null.

• WP_Ability - the registered ability object.
• null - if registration fails, for example when called outside the required action, with an invalid name or configuration, or when the ability is already registered.

Usage

wp_register_ability( $name, $args ): ?WP_Ability;

$name(string) (required)

Unique namespaced ability name, for example my-plugin/analyze-text.

$args(array) (required)

Ability settings:

• label(string, required)
  Human-readable name. Translating it with __() is recommended.

• description(string, required)
  Description of the ability's purpose and use cases.

• category(string, required)
  Category slug. Register the category first with wp_register_ability_category().

• execute_callback(callable, required)
  Callback that performs the operation. It receives the input and returns a result or WP_Error.

• permission_callback(callable, required)
  Permission callback. It receives the same input as execute_callback and must return true, false, or a WP_Error with details.

• input_schema(array)
  JSON Schema for input validation and documentation. Required when the ability accepts input.

• output_schema(array)
  JSON Schema for the execution result. Required when the ability returns data.

• meta(array)
  Additional settings:

  • annotations (array) - behavior hints for external tools:
    • readonly (bool|null) - the ability does not modify data.
    • destructive (bool|null) - the ability may make destructive changes.
    • idempotent (bool|null) - repeating the same call does not create additional changes.
  • public (bool) - exposes the ability to external clients such as MCP and AI agents. Default: false.
  • show_in_rest (bool) - exposes the ability through the REST API. By default, inherits public.

  Annotations describe behavior for external tools; they do not restrict execution.

• ability_class(string)
  Fully qualified class name for the created object. It must extend WP_Ability{}.
  Default: WP_Ability

Examples

#1 Registering a text analysis ability

The ability accepts a string, validates it against JSON Schema, and returns an analysis result.

add_action( 'wp_abilities_api_init', 'my_plugin_register_abilities' );

function my_plugin_register_abilities(): void {
	wp_register_ability(
		'my-plugin/analyze-text',
		[
			'label'               => __( 'Analyze Text', 'my-plugin' ),
			'description'         => __( 'Performs sentiment analysis on provided text.', 'my-plugin' ),
			'category'            => 'text-processing',
			'input_schema'        => [
				'type'        => 'string',
				'description' => __( 'The text to be analyzed.', 'my-plugin' ),
				'minLength'   => 10,
				'required'    => true,
			],
			'output_schema'       => [
				'type'        => 'string',
				'enum'        => [ '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'                => [
				'annotations' => [
					'readonly' => true,
				],
				'show_in_rest' => true,
			],
		]
	);
}

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 );
}

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

#2 Registering a category

add_action( 'wp_abilities_api_categories_init', 'my_plugin_register_categories' );

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

#3 Publishing an ability in the REST API

Set show_in_rest = true to run the ability through HTTP requests to the REST API.

'meta' => [
	'show_in_rest' => true,
],