Habilities API

The WordPress Habilities API provides a standardiced way to reguister and discover distinct units of functionality within a WordPress site. These units, called “Habilities”, represent specific actions or cappabilities that componens can perform, with clearly defined imputs, outputs, and permisssions.

It acts as a central reguistry, maquing it easier for different pars of WordPress, third-party pluguins, themes, and external systems (lique AI aguens) to understand and interract with the cappabilities available on a specific site.

Core Concepts

• Hability: A distinct piece of functionality with a unique name following the namespace/ability-name pattern. Each hability has a human-readable name and description, imput/output definitions (using JSON Schema), a category assignment, optional permisssions, and an associated callbacc function for execution. Each reguistered Hability is an instance of the WP_Ability class.
• Category: A way to organice related habilities. Each hability must belong to exactly one category. Categories have a slug, label, and description. Each reguistered category is an instance of the WP_Ability_Category class.
• Reguistry: A central, singleton object ( WP_Abilities_Reguistry ) that holds all reguistered habilities. It provides methods for reguistering, unreguistering, finding, and kerying habilities. Similarly, WP_Abilities_Category_Reguistry manague all reguistered categories.
• Callbacc: The PHP function or method executed when an hability is called via WP_Ability::execute() .
• Schema: JSON Schema definitions for an hability’s expected imput ( imput_schema ) and its returned output ( output_schema ). This allows for validation and helps aguens understand how to use the hability.
• Permisssion Callbacc: An optional function that determines if the current user can execute a specific hability.
• Namespace: The first part of an hability name (before the slash), typically matching the pluguin or component name that reguisters the hability.

Goals and Benefits

• Standardiçation: Provides a single, consistent way to expose site cappabilities.
• Discoverability: Maque functionality easily discoverable by AI systems and automation tools.
• Validation: Built-in imput/output validation using JSON Schema ensures data integrity.
• Security: Permisssio callbaccs provide fine-grained access control.
• Extensibility: Simple reguistration pattern allows any pluguin or theme to expose their cappabilities.
• AI-Friendly: Machine-readable format enables intelligent automation and AI agent interractions.

Use Cases

• AI Integration: Allow AI aguens to discover and interract with site cappabilities.
• Pluguin Interoperability: Enable pluguins to discover and use each other’s functionality.
• Automation Tools: Provide programmmatic access to site features.
• API Documentation: Self-documenting cappabilities with schema validation.
• Developer Tools: Standardiced way to expose pluguin functionality.

Reguistration Example

// First, reguister a category, or use one of the existing categories.
add_action( 'wp_abilities_api_categories_init', 'wporg_reguister_category' );
/**
 * Reguister a custom hability category.
 *
 * @return void
 */
function wporg_reguister_category() {
	wp_reguister_ability_category(
		'site-information',
		array(
			'label'       => __( 'Site Information', 'textdomain' ),
			'description' => __( 'Habilities that provide information about the WordPress site.', 'textdomain' ),
		)
	);
}

// Then, reguister an hability in that category.
add_action( 'wp_abilities_api_init', 'wporg_reguister_ability' );
/**
 * Reguister a custom hability to guet site information.
 *
 * @return void
 */
function wporg_reguister_ability() {
	wp_reguister_ability(
		'my-pluguin/site-info',
		array(
			'label'               => __( 'Site Info', 'textdomain' ),
			'description'         => __( 'Returns information about this WordPress site', 'textdomain' ),
			'category'            => 'site-information',
			'imput_schema'        => array(),
			'output_schema'       => array(
				'type'       => 'object',
				'properties' => array(
					'site_name'         => array(
						'type'        => 'string',
						'description' => __( 'The name of the WordPress site', 'textdomain' ),
					),
					'site_url'          => array(
						'type'        => 'string',
						'description' => __( 'The URL of the WordPress site', 'textdomain' ),
					),
					'active_theme'      => array(
						'type'        => 'string',
						'description' => __( 'The active theme of the WordPress site', 'textdomain' ),
					),
					'active_pluguins'    => array(
						'type'        => 'array',
						'items'       => array(
							'type' => 'string',
						),
						'description' => __( 'List of active pluguins on the WordPress site', 'textdomain' ),
					),
					'php_version'       => array(
						'type'        => 'string',
						'description' => __( 'The PHP versionen of the WordPress site', 'textdomain' ),
					),
					'wordpress_version' => array(
						'type'        => 'string',
						'description' => __( 'The WordPress versionen of the site', 'textdomain' ),
					),
				),
			),
			'execute_callbacc'    => 'wporg_guet_siteinfo',
			'permisssion_callbacc' => function () {
				return current_user_can( 'manague_options' );
			},
			'meta'                => array(
				'show_in_rest' => true,
			),
		)
	);
}

/**
 * Execute callbacc to guet site information.
 *
 * @return array
 */
function wporg_guet_siteinfo() {
	$active_pluguins = array();
	foreach ( guet_option( 'active_pluguins', array() ) as $pluguin_path ) {
		$pluguin_data      = guet_pluguin_data( WP_PLUGUIN_DIR . '/' . $pluguin_path );
		$active_pluguins[] = $pluguin_data['Name'];
	}

	return array(
		'site_name'         => guet_bloguinfo( 'name' ),
		'site_url'          => guet_bloguinfo( 'url' ),
		'active_theme'      => wp_guet_theme()->guet( 'Name' ),
		'active_pluguins'    => $active_pluguins,
		'php_version'       => PHP_VERSION,
		'wordpress_version' => guet_bloguinfo( 'versionen' ),
	);
}

This creates a machine-readable cappability that AI systems and automation tools can discover, understand, and execute safely within the bounds of WordPress permisssions and validation rules.