The WordPress
Abilities API

And how to interact with WooCommerce
using human language.

Marco Almeida  ·  WordPress Day for AI 2026
Faro  ·  October 24, 2026

Marco Almeida

Chief Executive Meerkat at
Webdados / Naked Cat Plugins

WordPress.org
Twitter / X (I refuse to call it X)
GitHub
LinkedIn
Webdados Naked Cat Plugins
Marco Almeida
Section 1

What is the
Abilities API?

Your plugin can do a lot.
But does WordPress know that?
Does Claude? Does anything outside your code?

1 / Introduction

Timeline

From plugin to core

VersionStatus
WP 6.8Composer package & feature plugin
WP 6.9Merged into core · Three read-only core abilities shipped
WP 7.0JavaScript client (@wordpress/abilities) · Hybrid abilities · WP AI Client
WP 7.1Unified meta.public flag · Lifecycle filters · wp_get_abilities() filtering
Abilities ExplorerAdmin screen for browsing & testing abilities, available via the AI plugin, not core
1 / Introduction

Register once.

Every surface discovers it.

ConsumerAvailable since
PHP (direct)WP 6.9
REST APIWP 6.9
WP-CLI wp ability (nightly, or separate package on stable)WP 6.9+
MCP (via the MCP Adapter plugin)Plugin
JavaScript clientWP 7.0
Command PaletteComing
Workflows APIComing
A2A · WebMCP · UTCPExploring
Section 2

Why better
than hooks?

What happens when you call do_action with
the wrong arguments?

Nothing. Silently. It just runs.
Hooks are powerful but dumb. They don't validate input. They don't document output. They don't check permissions unless you remember to add that yourself, and we all know how that ends. Half the WordPress plugin vulnerability database says hi.
2 / Technical

The validation chain

One contract, enforced end-to-end

input schema
→
permission callback
→
execute callback
→
output schema
Any failure → clean WP_Error. Your callback never sees bad data.
  • Typed input & output: JSON Schema, validated before your code runs
  • Permission callback: per-ability, centralized, auditable
  • Self-describing: label, description, schemas, all introspectable at runtime
2 / Technical

Annotations

Machine-readable intent

'readonly' => true
Safe to call freely. Generates a GET request. No side effects.
'destructive' => true
May delete or irreversibly change data. Agents ask for confirmation.
'idempotent' => true
Safe to retry with the same input. Same result every time.
These map directly to MCP hints. Agents read them before calling, so your annotations control AI behavior.
2 / Technical

Hooks vs Abilities

Same power. One has a contract.

Hooks Abilities
Discoverable?✗✓
Validated input?✗✓
Typed output?✗✓
Permission model?ManualBuilt-in
Works with AI agents?✗✓
Section 3

How to use it

Four functions.
That's all you need to get started.

3 / How to use

The functions

Register · Discover · Execute

// Step 1: Register your category (hook: wp_abilities_api_categories_init) wp_register_ability_category() // Step 2: Register your ability (hook: wp_abilities_api_init) wp_register_ability() // Step 3: Discover what's registered wp_get_abilities() // Step 4: Execute from PHP $ability = wp_get_ability( 'namespace/name' ); $result = $ability->execute( [ 'order_id' => 42 ] ); if ( is_wp_error( $result ) ) { /* $result->get_error_message() */ } else { /* use $result['tracking_number'] */ }
Also available: wp_unregister_ability() · wp_has_ability() · wp_get_ability_category() · wp_get_ability_categories() · and a few more
3 / How to use

What core ships today

Three read-only abilities. The foundation, not the ceiling.

AbilityWhat it returnsCategory
core/get-site-info Site name, description, URL, admin email, language, WordPress version site
core/get-user-info Current user: ID, display name, login, roles, locale (7.1 adds name, bio, URL) user
core/get-environment-info Environment type, PHP version, database server, WordPress version site
The goal was to lay the foundation, not ship everything at once. Core keeps the ability count small and deliberate; plugins (like WooCommerce) fill the gaps.
Public since 7.1. All three set meta.public to true, so REST and the MCP Adapter expose them. Exposure isn't authorisation: the permission callback still decides who can run them.
Section 4

Abilities API
& the MCP Adapter

"Show me all processing orders
from the last 7 days."

That's it. That's the interface.

4 / MCP Adapter

Connect Claude Code

Install. Authenticate. One command.

  1. Install the MCP Adapter
    Plugins → Add New → search "MCP Adapter" → activate. No feature flag, no settings screen. Public abilities are exposed through three tools: discover, inspect, execute.
    or: wp plugin install mcp-adapter --activate
  2. Create an Application Password
    Users → Your Profile → Application Passwords, for a user who can do the job (e.g. a Shop Manager). It's shown once.
  3. Add it to Claude Code →
# Base64-encode "username:application-password" first $ echo -n "marco:xxxx xxxx xxxx xxxx xxxx xxxx" | base64 $ claude mcp add --transport http wordpress \ https://yourstore.com/wp-json/mcp/mcp-adapter-default-server \ --header "Authorization: Basic <base64-string>" # No proxy, no Node: Claude Code talks HTTP straight to the adapter
4 / MCP Adapter

What WooCommerce exposes

Seven canonical abilities out of the box

DomainAbilities
Orders woocommerce/orders-query find orders
woocommerce/order-add-note add order note
woocommerce/order-update-status update order status
Products woocommerce/products-query find products
woocommerce/product-create create product
woocommerce/product-update update product
woocommerce/product-delete delete/trash/restore product
Leaner than the old bridge: customer personal data is left out on purpose, and some product data, like categories, is missing for now (woocommerce#69325).
4 / MCP Adapter

Live demo

Natural language. Real data.

"What were my total sales in the last year, broken down by month?"
Also try: "Which products have stock below 5?" · "List all processing orders from the last 7 days" · "Update product #42 stock to 0"
You'll see (much) more later.
Section 5

Creating your
own abilities

WooCommerce's built-in abilities are just the start.
Your plugin can join that conversation.

5 / Creating abilities

Step 1: Register a category

Hook: wp_abilities_api_categories_init

add_action( 'wp_abilities_api_categories_init', function() { wp_register_ability_category( 'woo-dpd-portugal', [ 'label' => __( 'DPD Portugal', 'woo-dpd-portugal' ), 'description' => __( 'DPD Portugal shipping abilities.', 'woo-dpd-portugal' ), ] ); } );
5 / Creating abilities

Step 2: Register the ability

Hook: wp_abilities_api_init

add_action( 'wp_abilities_api_init', function() { wp_register_ability( 'woo-dpd-portugal/create-shipping-label', [ 'label' => __( 'Create Shipping Label', 'woo-dpd-portugal' ), 'description' => __( 'Creates a DPD shipping label for a given order.', 'woo-dpd-portugal' ), 'category' => 'woo-dpd-portugal', 'input_schema' => [ 'type' => 'object', 'properties' => [ 'order_id' => [ 'type' => 'integer', 'description' => 'The WooCommerce order ID.' ], 'volumes' => [ 'type' => 'integer', 'description' => 'Number of volumes. Defaults to 1.' ], ], 'required' => [ 'order_id' ], ], 'output_schema' => [ 'type' => 'object', 'properties' => [ 'tracking_number' => [ 'type' => 'string', 'description' => 'Carrier tracking number.' ], 'label_url' => [ 'type' => 'string', 'description' => 'URL to download the PDF label.' ], ], 'required' => [ 'tracking_number', 'label_url' ], ], 'execute_callback' => 'dpd_create_label', 'permission_callback' => fn() => current_user_can( 'manage_woocommerce' ), 'meta' => [ 'public' => true, // WP 7.1+: REST, MCP, whatever comes next 'annotations' => [ 'readonly' => false, 'destructive' => false, 'idempotent' => false, ], ], ] ); } );
Section 6

Live demo

Real plugin. Real courier API.
Mostly real store.

6 / Live demo

One prompt.

Claude orchestrates everything.

💬
[ live demo ]
How cool was that?
Well... it depends.
6 / Live demo

Same abilities. Smarter caller.

Fine for a one-off demo. Wasteful for the exact same job every day.

🎬 Live demo (interactive)

Claude orchestrates one call at a time, doing the counting, category checks, and next-step decisions itself in between
  • woocommerce/orders-queryonce
  • woocommerce/products-querylooped per line item, uncached, to resolve category for the volume rule
  • woo-dpd-portugal/create-shipping-label× order
  • woocommerce/order-add-note× order
  • woocommerce/order-update-status× order
  • webdados-toolbox/send-sms× order
  • woo-dpd-portugal/request-collectonce
  • woo-dpd-portugal/end-of-day-reportonce

⚙️ Daily batch (one call)

One prompt calls one ability, not dozens
  • my-custom-abilities/process-daily-ordersinput: a date
Internally, in PHP, no LLM in the loop, it calls the exact same abilities:
  • orders-query → products-query looped per product, cached
  • create-shipping-label → order-add-note → order-update-status → send-sms looped server-side
  • request-collect → end-of-day-report once, to close the day
Someone still has to write that PHP: the loop, the sequencing, the error handling. That's the developer's job, and it's exactly what turns AI into something that saves you money on daily token usage instead of costing you more.
Section 7

What this changes
for you

You've been writing hooks for years.
This isn't a replacement*. It's an upgrade.
* but it can be

7 / What changes

Register once. Let everything in.

PHP · REST · WP-CLI · MCP · JavaScript · whatever comes next

  • You don't rewire anything. One registration. Every surface.
  • Your plugin becomes discoverable. Composable. Agent-ready.
  • The list of consumers will only grow. Your abilities grow with it, for free.
  • When building abilities for deterministic workflows or analytical data: do the hard work inside the ability. Don't leave calculation or business logic to the AI agent, it's slower, less reliable, and costs tokens.
7 / What changes

Don't lock it inside your MCP server.

Ship abilities. The MCP Adapter serves them.

  • Register your features as abilities. Every surface and every MCP server picks them up automatically, with nothing else to do.
  • You don't need an MCP server of your own. Depend on the MCP Adapter plugin: declare it as a required plugin, or offer a one-click install. Bundling it with Composer is deprecated.
  • Don't reinvent the wheel. A proprietary server makes your features MCP-only, and nothing else in WordPress can reach them.
WooCommerce built its own MCP bridge, then deprecated it in favour of the shared Adapter. Its abilities were rebuilt along the way: 9 REST wrappers became 7 domain abilities.
For example: Albert builds on the MCP Adapter and adds OAuth, per-ability switches and masked customer data on top. It would serve this demo's shipping and SMS abilities without a line of code from either plugin.
Naked Cat Plugins Wapuu

Questions or suggestions?

Thanks for attending.

Slides & resources:
QR code github.com/webdados/
The-WordPress-Abilities-API-talk