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
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
| Version | Status |
| WP 6.8 | Composer package & feature plugin |
| WP 6.9 | Merged into core · Three read-only core abilities shipped |
| WP 7.0 | JavaScript client (@wordpress/abilities) · Hybrid abilities · WP AI Client |
| WP 7.1 | Unified meta.public flag · Lifecycle filters · wp_get_abilities() filtering |
| Abilities Explorer | Admin screen for browsing & testing abilities, available via the AI plugin, not core |
1 / Introduction
Register once.
Every surface discovers it.
| Consumer | Available since |
| PHP (direct) | WP 6.9 |
| REST API | WP 6.9 |
WP-CLI wp ability (nightly, or separate package on stable) | WP 6.9+ |
| MCP (via the MCP Adapter plugin) | Plugin |
| JavaScript client | WP 7.0 |
| Command Palette | Coming |
| Workflows API | Coming |
| A2A · WebMCP · UTCP | Exploring |
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? | Manual | Built-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.
| Ability | What it returns | Category |
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.
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
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.
Add it to Claude Code →
$ 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>"
4 / MCP Adapter
What WooCommerce exposes
Seven canonical abilities out of the box
| Domain | Abilities |
| 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.
Questions or suggestions?
Thanks for attending.