The WordPress Abilities API: A Developer’s Guide to AI-Powered Blocks

Before the Abilities API, adding AI to a WordPress block meant every plugin did it differently. One plugin called OpenAI directly with its own bundled API key management. Another shipped its own LLM SDK. A third made raw fetch() calls to an external endpoint with authentication handled in JavaScript — visible to anyone who opened DevTools. The result: five AI-powered plugins on a site meant five different authentication schemes, five JavaScript bundles, and five different failure modes.

The Abilities API solves this at the architecture level. It’s a standardised interface between the block layer and AI models — a single place where Abilities are registered, authenticated, rate-limited, and served to any block that declares a need for them. Blocks don’t know which model they’re talking to. They request an Ability by name, pass context, and get a result.

This is what “model-agnostic” means in practice: change the underlying model from the WordPress admin panel, and every block that uses that Ability automatically uses the new model — without touching a line of block code.

What the Abilities API Actually Is

The Abilities API is a core WordPress framework with three layers:

1. The registry. A central server-side store of named Abilities — summarize, translate, tone-adjust, generate-alt-text, and any custom Abilities your theme or plugin registers. Each registered Ability declares: what AI model handles it, what input schema it accepts, what output format it returns, and what rate limits apply.

2. The block declaration. Blocks declare which Abilities they need in block.json. This is a static declaration — WordPress validates it at block registration time and won’t activate a block’s AI features if its required Abilities aren’t available.

3. The JavaScript API. In block edit/save scripts, wp.abilities.request() sends an Ability invocation to the WordPress REST endpoint that handles routing to the appropriate model. The block never sees API keys, never handles authentication, and never needs to know which model is active.

Compare this to the approach the WordPress Interactivity API guide describes for reactive UI — the Abilities API handles the AI side with the same philosophy: declarative at the block level, implementation handled by WordPress core.

Declaring Abilities in block.json

The block.json declaration is where a block announces what AI capabilities it needs:

{
  "name": "my-plugin/smart-summary",
  "title": "Smart Summary",
  "description": "Auto-generates a TL;DR from post content using the Abilities API.",
  "category": "text",
  "attributes": {
    "summary": {
      "type": "string",
      "default": ""
    }
  },
  "abilities": {
    "required": ["summarize"],
    "optional": ["translate"]
  },
  "editorScript": "file:./edit.js",
  "viewScript": "file:./view.js"
}

The "abilities" key takes required (block won’t function without this Ability) and optional (block degrades gracefully if the Ability isn’t available). WordPress validates this at registration and surfaces a notice in the editor if a required Ability is missing from the site’s registry.

Calling Abilities from Block JavaScript

In your block’s edit.js, wp.abilities.request() is the entry point. It returns a Promise that resolves to the model’s response, normalised to the output schema the Ability declared:

import { useBlockProps, RichText } from '@wordpress/block-editor';
import { Button } from '@wordpress/components';
import { useState } from '@wordpress/element';

export default function Edit( { attributes, setAttributes, context } ) {
    const blockProps = useBlockProps();
    const [ isLoading, setIsLoading ] = useState( false );

    async function generateSummary() {
        setIsLoading( true );
        try {
            const result = await wp.abilities.request( 'summarize', {
                content: context.postContent,
                maxLength: 150,
                format: 'plain',
            } );
            setAttributes( { summary: result.text } );
        } catch ( error ) {
            console.error( 'Ability request failed:', error.message );
        } finally {
            setIsLoading( false );
        }
    }

    return (
        <div { ...blockProps }>
            <Button
                onClick={ generateSummary }
                isBusy={ isLoading }
                variant="primary"
            >
                { isLoading ? 'Generating...' : 'Generate Summary' }
            </Button>
            { attributes.summary && (
                <RichText
                    tagName="p"
                    value={ attributes.summary }
                    onChange={ ( value ) => setAttributes( { summary: value } ) }
                />
            ) }
        </div>
    );
}

The block has no knowledge of which model handles summarize — it could be GPT-4o, Claude, Gemini, a fine-tuned open-source model, or a local Ollama instance. The Ability registry handles the routing.

Registering a Custom Ability in PHP

WordPress ships with a core set of built-in Abilities. To register a custom one — for example, a domain-specific classifier trained on your content:

<?php

add_action( 'init', 'register_custom_abilities' );

function register_custom_abilities() {
    if ( ! function_exists( 'wp_register_ability' ) ) {
        return; // Abilities API not available on this WordPress version
    }

    wp_register_ability( 'product-matcher', array(
        'label'          => 'Product Matcher',
        'description'    => 'Matches a customer query to relevant products from the catalog.',
        'model'          => 'openai/gpt-4o',
        'input_schema'   => array(
            'query'       => array( 'type' => 'string', 'required' => true ),
            'max_results' => array( 'type' => 'integer', 'default' => 5 ),
        ),
        'output_schema'  => array(
            'matches'    => array( 'type' => 'array' ),
            'confidence' => array( 'type' => 'number' ),
        ),
        'rate_limit'     => array(
            'requests_per_minute' => 20,
            'per'                 => 'user',
        ),
        'capability'     => 'read',
    ) );
}

The model value uses a provider/model-id notation. Swapping openai/gpt-4o for anthropic/claude-3-5-sonnet here changes every block that uses product-matcher — no block code changes required. This is the model-agnostic benefit in practice.

The Security Model

The Abilities API’s security advantages over per-plugin AI integrations:

Centralised API key management. Keys live in wp-config.php or WordPress options, server-side. No block ships its own API key in JavaScript. No key is visible in DevTools network requests.

Capability gating. The capability parameter in wp_register_ability() specifies which WordPress user capability is required to invoke an Ability. A translate Ability might require only read; a generate-post Ability might require publish_posts. AI features automatically respect your user role structure.

Rate limiting. Declared in the Ability registration. Per-user, per-site, or per-block rate limits prevent runaway API costs and abuse without custom code in every block.

Audit logging. Every Ability invocation is logged with the invoking user, the Ability name, token counts (where the model reports them), and any error. Site administrators get a centralised view of AI usage across all blocks and plugins.

For the broader WordPress security context, the same principles that govern plugin permission handling apply to AI features — covered in the integrating AI in WordPress guide.

Core Built-In Abilities

WordPress ships with a set of standard Abilities that blocks can use immediately without custom registration:

Ability name	What it does	Typical use
summarize	Condenses long content to a specified length	TL;DR blocks, excerpt generation
translate	Translates content to a target language	Multilingual content workflows
tone-adjust	Rewrites content in a different register (formal, casual, technical)	Editorial style tools
generate-alt-text	Writes descriptive alt text for an image	Accessibility automation
classify	Assigns a category or tag from a defined taxonomy	Content organisation
fact-check	Verifies a claim against a provided knowledge base	Editorial quality gates
suggest-links	Proposes internal links from the site’s content index	Internal linking automation

The suggest-links Ability is particularly relevant to the collaborative editorial workflows described in the collaborative editing guide — it’s the mechanism behind real-time AI-assisted internal linking as a writer types.

Building a Tone Switcher Block

A concrete example: a block that rewrites a paragraph in a different tone on demand.

block.json:

{
  "name": "my-plugin/tone-switcher",
  "title": "Tone Switcher",
  "abilities": {
    "required": ["tone-adjust"]
  },
  "attributes": {
    "content":         { "type": "string", "default": "" },
    "originalContent": { "type": "string", "default": "" },
    "activeTone":      { "type": "string", "default": "professional" }
  },
  "editorScript": "file:./edit.js"
}

edit.js — core Ability call:

const TONES = ['professional', 'conversational', 'witty', 'technical'];

async function applyTone( content, tone, setAttributes ) {
    const result = await wp.abilities.request( 'tone-adjust', {
        content,
        targetTone: tone,
        preserveLength: true,
    } );
    setAttributes( {
        content: result.text,
        activeTone: tone,
    } );
}

The block stores originalContent on first edit so the user can always revert. The tone switch is non-destructive — the Ability returns a new string, not a diff applied to the existing content.

Abilities API and Gutenberg Phase 3

The Abilities API isn’t confined to single-user content creation. In Gutenberg Phase 3 (the Collaboration phase), AI agents participate in editorial sessions as registered participants — and they interact with the editor through the same Abilities they’d call from a block.

An AI agent assigned to review a draft can call fact-check on specific paragraphs, suggest-links as the human writer types, and tone-adjust to flag sections that drift from the site’s style guide — all via the same Ability interface, with the same permission gating and audit logging as any other Ability invocation. The collaborative editing guide covers how AI agents slot into Phase 3 editorial workflows in full.

Performance and Core Web Vitals

The centralised architecture has a direct performance benefit. Instead of five AI plugins each loading their own SDK — adding 100–300KB of JavaScript per plugin — the Abilities API ships one shared JavaScript module. Blocks that use Abilities don’t load AI logic; they call a pre-loaded API.

AI features that trigger server-side (Abilities requested on post save or via a REST call) add no client-side JavaScript at all. Abilities triggered interactively in the editor are editor-only scripts — they don’t load on the published page. The result: AI-powered blocks can have zero impact on frontend performance.

For the full block performance picture, high-performance block themes covers the editor-vs-frontend script separation pattern. The SEO implications of AI-generated content quality are covered in the GEO optimisation guide — AI-generated content that answers specific questions well ranks better than generic content, regardless of whether it was drafted by a human or an Ability. For the full context of where AI fits in WordPress development, see AI-powered WordPress development.

When to Use the Abilities API vs. Direct Model Integration

Use the Abilities API when:

• You’re building blocks for distribution (themes, plugins sold or shared with others)
• You need model flexibility — the model choice should be configurable by the site admin
• Multiple blocks on the same site will use AI — centralised auth and rate limiting matters
• You need audit logging of AI usage per user

Direct model integration makes sense when:

• You’re building a one-off server-side tool for a specific site that will never be distributed
• The integration is entirely PHP-side — a scheduled process that generates content, not a block
• You need streaming responses or model features the Abilities API doesn’t yet expose

The WooCommerce AI personalisation guide shows a concrete application of registered Abilities in a RAG-based product recommendation system — a useful reference for the direct-vs-API tradeoff on a real project.

Getting Started

The Abilities API requires WordPress 6.7+. Always check for availability before using it:

// PHP
if ( function_exists( 'wp_register_ability' ) ) {
    // Abilities API is available
}

// JavaScript
if ( wp.abilities && wp.abilities.request ) {
    // Abilities API is available in the editor
}

Blocks should degrade gracefully when a required Ability isn’t available — surface a clear message in the editor rather than a broken UI or a silent failure.

For custom Ability development scoped to a specific workflow — including custom model routing, rate limiting configuration, and audit logging setup — the WordPress plugin development service covers Abilities API registration as part of custom plugin builds. The Full Site Editing guide provides the broader block ecosystem context for where Abilities-powered blocks fit into modern WordPress theme architecture.