DEV Community: Alok Jain

Register your first WordPress ability

Alok Jain — Fri, 16 Oct 2026 07:59:50 +0000

Until now, every plugin that wanted an AI agent (or any outside tool) to do something on a WordPress site had to invent its own REST endpoints, its own permission checks and its own way of describing what they do. WordPress 6.9 added the Abilities API , a single registry where plugins describe what they can do in a format both code and AI agents can read.

An ability is one named action: a label, a description, input and output schemas, a permission check, and the callback that does the work. This issue registers a small read-only one that counts draft posts.

1. Register a category

Every ability belongs to a category, so register that first:

add_action( 'wp_abilities_api_categories_init', function () {
    wp_register_ability_category( 'hsr-content', array(
        'label'       => __( 'Content', 'hsr' ),
        'description' => __( 'Abilities that read site content.', 'hsr' ),
    ) );
} );

Category slugs use lowercase letters, numbers and dashes only.

2. Register the ability

add_action( 'wp_abilities_api_init', function () {
    wp_register_ability( 'hsr/count-drafts', array(
        'label'               => __( 'Count drafts', 'hsr' ),
        'description'         => __( 'Returns the number of draft posts on the site.', 'hsr' ),
        'category'            => 'hsr-content',
        'output_schema'       => array(
            'type'       => 'object',
            'properties' => array(
                'drafts' => array( 'type' => 'integer' ),
            ),
        ),
        'execute_callback'    => function () {
            $counts = wp_count_posts( 'post' );
            return array( 'drafts' => (int) $counts->draft );
        },
        'permission_callback' => function () {
            return current_user_can( 'edit_posts' );
        },
        'meta'                => array(
            'show_in_rest' => true,
            'annotations'  => array( 'readonly' => true ),
        ),
    ) );
} );

The array passed to wp_register_ability() reads top to bottom as four groups: what the ability is called, what it returns, what it does, and who’s allowed to run it.

Naming it. The first argument, hsr/count-drafts, is the ability’s unique name. It has to follow the namespace/ability-name format, and the namespace should be your plugin’s slug so it can’t clash with anyone else’s.

label is the short human-readable name a UI would show. description is the longer explanation, and it matters more than it looks: when an AI agent is choosing which ability to call, this is the text it reads. Write it for someone who has never seen your code.

category must match a slug you’ve already registered, which is why section 1 comes first. If it doesn’t match, WordPress won’t register the ability and you’ll find a “doing it wrong” notice in debug.log.

Describing the result. output_schema is a JSON Schema describing what the ability returns. Here it says “an object with one key, drafts, which is an integer.”

This isn’t just documentation. WordPress checks the callback’s return value against this schema, and if it doesn’t match, the caller gets an error instead of the result.

This ability takes no input, so there’s no input_schema. When an ability does need input, that key describes it in the same JSON Schema format and WordPress validates it before your callback runs.

Doing the work. execute_callback is the function that actually runs. wp_count_posts( 'post' ) returns an object with one property per post status, and we pick out draft.

The (int) cast is there because of the schema. The counts come from the database as strings ("3", not 3), and a string would fail the integer check.

Checking permission. permission_callback runs before execute_callback, every time. If it returns false, the callback never runs. Here it requires edit_posts, which contributors and every role above them have.

The extra settings. meta holds options that sit outside the core definition. show_in_rest makes the ability visible and runnable through the REST API, and is off by default. The readonly annotation tells callers (including AI agents) that running it won’t change anything on the site.

Warning: with show_in_rest on, the permission callback is the only thing between this ability and anyone who can reach your REST API.

Returning true from it means every visitor succeeds, logged in or not.

For a draft count that’s a small leak. For an ability that updates posts or reads customer data, it’s a real hole, so always check a specific capability.

3. Run it

From WP-CLI, as a user who can edit posts:

wp eval 'print_r( wp_get_ability( "hsr/count-drafts" )->execute() );' --user=admin

You should see an array with a drafts key and your actual draft count. Run it without --user and the permission check fails, which is a quick way to confirm the callback is doing its job.

Over REST, with an application password:

curl -u admin:YOUR_APP_PASSWORD https://yoursite.test/wp-json/wp-abilities/v1/abilities/hsr/count-drafts/run

Same result, as JSON. That same registered ability is what the MCP Adapter hands to AI agents like Claude, which I’ll cover in a later issue.

That’s all for this one.

Try it: register a second read-only ability that returns the number of pending comments (wp_count_comments() will get you there). Tell me what you wrote for its description, I’m curious how different everyone’s are.

The post Register your first WordPress ability first appeared on alokjain.dev.

Stop your staging site from emailing real customers

Alok Jain — Fri, 09 Oct 2026 10:00:28 +0000

When you copy a live database to staging, you copy every customer email address with it. Then a cron job runs, a WooCommerce order gets resent while you’re testing, or a form plugin fires a notification, and a real person gets an email from your staging site.

WordPress 5.5 added a clean way to tell a site which environment it’s running in. Once the site knows it’s staging, you can block outgoing mail there and leave production alone.

1. Set the environment in wp-config.php

On the staging server, add this to wp-config.php above the “That’s all, stop editing!” line:

define( 'WP_ENVIRONMENT_TYPE', 'staging' );

The accepted values are local, development, staging and production. If the constant isn’t set, or is set to anything else, WordPress treats the site as production.

Because this lives in wp-config.php and not in the database, it survives every database copy. That’s the whole reason to use it over an option or a setting.

2. Block mail outside production

Save this as wp-content/mu-plugins/block-staging-mail.php (create the mu-plugins folder if it doesn’t exist):

<?php
/**
 * Plugin Name: Block Mail Outside Production
 */

add_filter( 'pre_wp_mail', function ( $return, $atts ) {
    if ( 'production' === wp_get_environment_type() ) {
        return $return;
    }

    $to = is_array( $atts['to'] ) ? implode( ', ', $atts['to'] ) : $atts['to'];

    error_log( sprintf(
        'Mail blocked on %s: "%s" to %s',
        wp_get_environment_type(),
        $atts['subject'],
        $to
    ) );

    return true;
}, 10, 2 );

pre_wp_mail runs before wp_mail() does any work. If the filter returns anything other than null, WordPress skips sending and uses that value as the result.

Returning true tells the calling plugin the mail went out fine. On staging that’s what you want, so contact forms and checkouts don’t show “email failed” errors while you test.

I put this in a must-use plugin rather than the theme so it keeps working if someone switches themes on staging, and nobody can deactivate it from the Plugins screen.

3. Test it with WP-CLI

Confirm the environment first:

wp eval 'echo wp_get_environment_type();'

Then send a test mail:

wp eval 'wp_mail( "you@example.com", "Staging test", "Hello from staging" );'

Nothing should arrive, and debug.log should have a “Mail blocked on staging” line (this needs WP_DEBUG and WP_DEBUG_LOG set to true).

Warning: this only catches mail sent through wp_mail().

Most plugins use it, including SMTP plugins, which hook in further down and never get reached.

A plugin that talks directly to an email service’s API (some newsletter and transactional mail plugins do this) bypasses wp_mail() completely. For those, check the plugin’s own settings for a test or sandbox mode.

That’s all for this one.

Try it: add the constant to your staging site, drop in the mu-plugin, then place a test order or submit a form. Check debug.log and tell me which plugin’s email showed up first.

The post Stop your staging site from emailing real customers first appeared on alokjain.dev.

Add a skip link to a classic theme

Alok Jain — Fri, 02 Oct 2026 10:00:18 +0000

Keyboard users press Tab to move through a page, and on most sites the first twenty or so stops are header links and menu items. A skip link is a hidden link at the very top that appears on the first Tab press and jumps straight to the main content.

Block themes get one automatically (WordPress has added it since 5.8, pointing at the template’s <main> element). Classic themes don’t, unless the theme author built one in.

Before adding anything, open your site, click in the address bar, and press Tab once. If a “Skip to content” link shows up in a corner, your theme already has one and you can stop here. Themes built on Underscores usually do.

1. Print the link with wp_body_open

add_action( 'wp_body_open', function () {
    echo '<a class="skip-link screen-reader-text" href="#primary">' . esc_html__( 'Skip to content', 'hsr' ) . '</a>';
}, 5 );

wp_body_open fires right after the opening <body> tag, which is exactly where a skip link needs to be so it’s the first thing Tab reaches. The priority of 5 puts it ahead of anything else hooked there.

The href has to match the id of your main content wrapper. I used #primary because a lot of classic themes use it, but check your theme’s index.php or page.php for the real one (#content and #main are common too).

Warning: wp_body_open only works if the theme calls it.

The function was added in WordPress 5.2, and themes older than that often skip it. If your link never appears, open header.php and look for wp_body_open(); right after the <body> tag.

If it’s missing, add it there. For a third-party theme, do this in a child theme’s copy of header.php, or the next theme update will wipe it.

2. Hide it until it gets focus

.screen-reader-text {
    border: 0;
    clip-path: inset(50%);
    height: 1px;
    margin: -1px;
    overflow: hidden;
    padding: 0;
    position: absolute;
    width: 1px;
    word-wrap: normal !important;
}

.skip-link.screen-reader-text:focus {
    background: #fff;
    clip-path: none;
    color: #1e1e1e;
    display: block;
    font-weight: 600;
    height: auto;
    left: 8px;
    margin: 0;
    padding: 12px 20px;
    text-decoration: none;
    top: 8px;
    width: auto;
    z-index: 100000;
}

The first rule is the standard screen-reader-text pattern WordPress core uses in the admin. It hides the link visually but keeps it readable by screen readers, which display: none would not.

The second rule brings it back when it receives keyboard focus. The z-index of 100000 keeps it above the admin bar when you’re logged in (the admin bar sits at 99999).

3. Test it with the keyboard

Reload the page, click in the address bar, and press Tab. The link should appear at the top left.

Press Enter, then Tab again. Focus should land on the first link inside your main content, not back in the header menu.

If it jumps back to the header, the id in the href doesn’t match anything on the page. View source and search for it.

That’s all for this one.

Try it: Tab through your homepage without the skip link first and count how many presses it takes to reach the first link in your content. Then add the snippet and count again. Tell me the before number, I’m guessing some of you will cross 30.

The post Add a skip link to a classic theme first appeared on alokjain.dev.

Defer scripts with wp_enqueue_script()

Alok Jain — Fri, 25 Sep 2026 10:00:23 +0000

A lot of themes still load every script in the <head>, so the browser has to download and run each one before it can finish rendering the page. The old workaround was a script_loader_tag filter that string-replaced <script with <script defer.

WordPress 6.3 added a proper way to do this. The fifth argument of wp_enqueue_script(), which used to be only true or false for footer loading, now also accepts an array with a loading strategy.

1. Defer a script you enqueue

add_action( 'wp_enqueue_scripts', function () {
    wp_enqueue_script(
        'hsr-slider',
        get_stylesheet_directory_uri() . '/js/slider.js',
        array(),
        '1.0.0',
        array(
            'strategy' => 'defer',
            'in_footer' => true,
        )
    );
} );

strategy takes defer or async. Both let the browser keep building the page while the script downloads, which a normal script tag doesn’t.

The difference is when they run. A deferred script waits until the HTML is fully parsed, and deferred scripts run in the order they were added. An async script runs the moment it finishes downloading, so there’s no guaranteed order.

I use defer for almost everything. async only makes sense for scripts that don’t depend on anything and nothing depends on them, like some analytics tags.

2. Defer a script from a plugin

You don’t need to edit the plugin. Find the script’s handle in the page source (it’s the id on the script tag, without the -js at the end) and set the strategy after the plugin registers it:

add_action( 'wp_enqueue_scripts', function () {
    wp_script_add_data( 'some-plugin-script', 'strategy', 'defer' );
}, 20 );

wp_script_add_data() attaches extra data to a script that’s already registered. It takes three things: the handle, a key, and a value. When you pass strategy in the enqueue array like in snippet 1, WordPress stores it this same way behind the scenes, so both snippets end up in the same place.

The catch is that it only works on a registered handle. If the plugin hasn’t registered its script yet when your code runs, the function returns false and nothing happens.

That’s why the priority is 20. It makes this run after the plugin’s own enqueue, which usually sits at the default 10.

If you’re not sure the timing is right, check the return value while testing:

add_action( 'wp_enqueue_scripts', function () {
    if ( ! wp_script_add_data( 'some-plugin-script', 'strategy', 'defer' ) ) {
        error_log( 'some-plugin-script is not registered yet' );
    }
}, 20 );

If that line shows up in debug.log, the plugin registers its script later than priority 20 (some use a higher priority or a different hook), so bump the number up and try again.

3. Check that it worked

View source and find the script tag. If WordPress applied the strategy, you’ll see defer data-wp-strategy="defer" on it.

If the attribute is missing, look at what depends on that script. WordPress won’t defer a script when something depending on it still loads normally, and it falls back without any notice.

Warning: leave jQuery out of this.

Plenty of themes and plugins print inline code in the page that calls jQuery(...) right away. If jQuery is deferred, that code runs before jQuery exists.

You’ll see it as jQuery is not defined in the browser console, usually along with a slider or menu that quietly stops working.

That’s all for this one.

Try it: pick one non-jQuery script loading in your homepage <head> and defer it with snippet 2. If it didn’t get the data-wp-strategy attribute, tell me which plugin’s script held it back.

The post Defer scripts with wp_enqueue_script() first appeared on alokjain.dev.