The WordPress Abilities API: registering abilities and how they connect to AI

The Abilities API is a registry of the things a WordPress site can do. Each "ability" is a named, self-describing action, such as "get site information" or "create a draft," with a JSON Schema for its input and output, a permission check and a PHP callback that does the work. Plugins, themes, WP-CLI, the REST API and AI tools can all discover and call the same abilities in the same way.

It shipped in WordPress 6.9 (December 2025), whose release post called it "a standardized registry" that is "opening doors for AI-powered workflows." WordPress 7.0 (May 2026) added a JavaScript counterpart and an AI Client that works with abilities, plus a Connectors screen for AI provider credentials. WordPress 7.1 (August 2026) refined discovery, exposure and validation.

This guide explains the concepts, shows how to register and execute an ability, covers REST and JavaScript access, and describes how abilities fit with the AI Client, Connectors and the MCP Adapter, based only on what the official documentation and Make WordPress posts say as of October 2026.

Core concepts

The Abilities API handbook defines five building blocks:

• Ability: a unit of functionality named namespace/ability-name (lowercase letters, numbers, hyphens and one slash), represented by a WP_Ability object.
• Category: a group of related abilities. Every ability belongs to exactly one category, and categories must be registered first.
• Registry: the singleton WP_Abilities_Registry (and WP_Abilities_Category_Registry for categories) that holds everything registered.
• Schema: JSON Schema for input_schema and output_schema, used for validation and so that agents know how to call the ability.
• Permission callback: decides whether the current user may execute the ability.

The handbook lists the intended uses: AI integration, plugin interoperability, automation tools, self-documenting APIs and developer tools. The common thread is that a caller does not need to know your plugin's internal functions; it only needs the ability name and schema.

Registering a category and an ability

Registration happens on two dedicated hooks. Abilities registered elsewhere are rejected, which guarantees the registry is ready.

1. Register a category: add_action( 'wp_abilities_api_categories_init', function () { wp_register_ability_category( 'content-tools', array( 'label' => __( 'Content tools', 'my-plugin' ), 'description' => __( 'Abilities that read or prepare site content.', 'my-plugin' ) ) ); } );
2. Register the ability: add_action( 'wp_abilities_api_init', function () { wp_register_ability( 'my-plugin/count-drafts', array( 'label' => __( 'Count drafts', 'my-plugin' ), 'description' => __( 'Returns the number of draft posts of a given post type.', 'my-plugin' ), 'category' => 'content-tools', 'input_schema' => array( 'type' => 'object', 'properties' => array( 'post_type' => array( 'type' => 'string', 'default' => 'post' ) ) ), 'output_schema' => array( 'type' => 'integer' ), 'execute_callback' => 'my_plugin_count_drafts', 'permission_callback' => function () { return current_user_can( 'edit_posts' ); }, 'meta' => array( 'annotations' => array( 'readonly' => true, 'destructive' => false ), 'show_in_rest' => true ) ) ); } );
3. Write the callback: function my_plugin_count_drafts( $input ) { $post_type = sanitize_key( $input['post_type'] ?? 'post' ); if ( ! post_type_exists( $post_type ) ) { return new WP_Error( 'invalid_post_type', __( 'Unknown post type.', 'my-plugin' ) ); } $counts = wp_count_posts( $post_type ); return (int) $counts->draft; }

The callback returns a value that matches output_schema, or a WP_Error. If the input fails schema validation, the permission callback is never called and a WP_Error is returned instead. Note that a more careful version would also check the post type's own edit capability; edit_posts keeps the example short.

Registration arguments

Annotations matter more than they look. They tell agents whether an ability only reads data, whether it may delete or overwrite things and whether repeating a call is safe, and the REST API uses them to decide which HTTP method an ability requires.

Executing abilities in PHP

Any code can look up an ability and run it: $ability = wp_get_ability( 'my-plugin/count-drafts' ); if ( $ability ) { $result = $ability->execute( array( 'post_type' => 'page' ) ); if ( is_wp_error( $result ) ) { error_log( $result->get_error_message() ); } }. execute() validates input, checks permissions for the current user, runs the callback and validates output.

Other functions in the PHP reference include wp_get_abilities() (all registered abilities; WordPress 7.1 added filtering), wp_unregister_ability(), wp_get_ability_category(), wp_get_ability_categories() and $ability->check_permissions(). Hooks let you observe or adjust behavior: wp_before_execute_ability and wp_after_execute_ability actions fire around execution, and the wp_register_ability_args filter can modify an ability's arguments as it is registered. WordPress 7.1 added further execution lifecycle filters.

To support sites older than 6.9, check class_exists( 'WP_Ability' ) and show an admin notice instead of registering.

REST API and WP-CLI access

Abilities are hidden from the REST API unless they opt in. With show_in_rest (or, since 7.1, public) set to true in meta, an ability appears under the wp-abilities/v1 namespace:

• GET /wp-json/wp-abilities/v1/abilities lists exposed abilities; GET /wp-json/wp-abilities/v1/categories lists categories.
• GET /wp-json/wp-abilities/v1/my-plugin/count-drafts returns one ability's definition.
• /wp-json/wp-abilities/v1/my-plugin/count-drafts/run executes it. Read-only abilities use GET (input as a URL-encoded JSON input parameter), abilities that change data use POST with {"input": {...}} in the body, and destructive abilities use DELETE.

All of these endpoints require an authenticated user, and execution still runs the ability's permission_callback. The handbook lists cookie authentication for same-origin requests and recommends application passwords for external access; see our WordPress REST API guide for both.

The WP-CLI command reference also documents wp ability, with subcommands list, get, run, exists, can-run, validate and category, for example wp ability run core/get-site-info --user=admin. Our WP-CLI guide explains how to get it if your installed version lacks the command.

Exposure in WordPress 7.1: the public flag

As MCP adapters and other clients arrived, setting a separate exposure flag for every channel became repetitive. The 7.1 dev note introduced meta public: when true, show_in_rest defaults to true, and other integrations can use it as their default. Channel-specific settings still win, so 'public' => true with 'show_in_rest' => false keeps an ability out of REST. The note says the WordPress MCP Adapter would respect the flag from its next release, while WP-CLI's listing returns all registered abilities regardless.

The same note is blunt about security: "Exposure is not authorisation." The public flag affects discoverability only, and every ability still needs an appropriate permission_callback.

Client-side abilities in WordPress 7.0

WordPress 7.0 added a JavaScript API for abilities that run in the browser, such as navigating to a screen or inserting blocks, which the dev note describes as fundamental for browser agents and WebMCP. It comes in two script modules:

• @wordpress/abilities: the store, registration, querying and execution logic, with no server dependencies.
• @wordpress/core-abilities: the WordPress integration layer, which fetches server-registered abilities and categories from the REST API and registers them in the client store.

Enqueue the integration with wp_enqueue_script_module( '@wordpress/core-abilities' ) on admin_enqueue_scripts, then call registerAbility(), getAbilities() and executeAbility() imported from @wordpress/abilities. Client abilities use JSON Schema (draft-04) and can define a permissionCallback. The 7.0 Field Guide adds that client-side abilities come with a UI and Command Palette integration.

How abilities relate to the AI Client and Connectors

These are three separate pieces that are designed to work together:

The AI Client dev note says the WordPress wrapper (WP_AI_Client_Prompt_Builder) integrates with "the Abilities API, the Connectors/Settings infrastructure, and the WordPress hooks," and the 7.0 Field Guide says the Abilities API "is integrated directly into the WP AI Client." In practice, abilities are the "tools" a model can be offered. A July 2026 merge proposal put it plainly: core abilities give "the AI Client (merged in 7.0) something real to call as tools."

Two points from the official posts are worth repeating to clients. First, core "does not ship any AI providers or automatically enable AI calls," so nothing is sent anywhere without configuration and calling code. Second, provider plugins (WordPress.org publishes ones for Anthropic, Google and OpenAI) supply the models, and a wp_ai_client_prevent_prompt filter lets site owners block prompts, for example for non-administrators. Our overview of what's new in WordPress 7.0 and 7.1 covers the user-facing side.

The WordPress Developer Blog describes the MCP Adapter as "an official package in the AI Building Blocks for WordPress initiative" that turns abilities into MCP tools and resources, so AI clients can discover and call them. It is not part of core.

Core abilities and what is planned

WordPress 6.9 ships three abilities: core/get-site-info, core/get-user-info (the current user's basic profile) and core/get-environment-info. In 7.1 they were updated to use the new public flag.

A July 2026 merge proposal suggested read-only core/read-settings, core/read-content and core/read-users abilities, with settings and post types opting in through a show_in_abilities flag, and "manage" abilities for 7.2 and beyond. Treat these as proposals: check the current release notes before depending on them. The same proposal notes that prompt-injection protection for ability results is out of scope, and that agents "must treat them as tool output, not instructions to follow."

Use cases and design advice

• Expose plugin actions once. A booking plugin can register "list open slots" and "create booking" abilities and get REST, WP-CLI and AI access from one definition.
• Plugin interoperability. Other plugins can call your ability by name instead of your internal functions, which can change. Keeping abilities as a thin layer over a well-structured service class fits the patterns in our WordPress plugin architecture guide.
• Admin automation. Editors can trigger abilities from the Command Palette through client-side abilities.
• Agent access with guardrails. Pair abilities with a dedicated low-privilege user and application password when connecting an external agent.

Write descriptions for a reader who has never seen your plugin, keep abilities small and single-purpose, annotate them honestly (readonly, destructive, idempotent), and expose only what a remote client genuinely needs. Security principles from our plugin security guide apply unchanged: validate input, check capabilities and never return secrets.

Conclusion

The Abilities API gives WordPress a shared, typed vocabulary for actions. Register a category and an ability, define schemas and a permission callback, and the same action becomes available to PHP, REST, WP-CLI, the browser and, through the AI Client or MCP Adapter, to AI tools. The 7.1 public flag simplifies exposure, but authorization still lives in your permission_callback. More developer guides are in our WordPress hub, and if you want abilities designed into a custom plugin, eSEOspace offers WordPress plugin development.

Frequently asked questions