name	wp-abilities-api
description	Use when working with the WordPress Abilities API: wp_register_ability, wp_register_ability_category, /wp-json/wp-abilities/v1/*, @wordpress/abilities for defining abilities, categories, REST exposure, and permission checks for clients.
compatibility	Targets WordPress 6.9+ (PHP 8.0+). Abilities API may require plugin for older versions.

WP Abilities API

When to use

Use this skill when the task involves:

Registering abilities or ability categories in PHP
Exposing abilities to clients via REST (wp-abilities/v1)
Consuming abilities in JS (@wordpress/abilities)
Diagnosing "ability doesn't show up" / "client can't see ability"

Inputs required

Repo root and project type
Target WordPress version(s)
Where the change should live (plugin vs theme vs mu-plugin)

Procedure

1) Register an ability category (optional)

Categories group related abilities:

add_action('wp_abilities_api_categories_init', function() {
    wp_register_ability_category('my-plugin-features', array(
        'label'       => __('My Plugin Features', 'my-plugin'),
        'description' => __('Feature flags for My Plugin', 'my-plugin'),
    ));
});

2) Register abilities

add_action('wp_abilities_api_init', function() {
    wp_register_ability('my-plugin/can-export', array(
        'label'       => __('Can Export Data', 'my-plugin'),
        'description' => __('User can export their data', 'my-plugin'),
        'category'    => 'my-plugin-features',
        'meta'        => array(
            'readonly'     => false,
            'show_in_rest' => true,
        ),
    ));
});

3) Check ability in PHP

if (current_user_has_ability('my-plugin/can-export')) {
    // User has this ability
}

4) Expose via REST API

Abilities with show_in_rest: true are available at:

GET /wp-json/wp-abilities/v1/abilities
GET /wp-json/wp-abilities/v1/abilities/my-plugin%2Fcan-export
GET /wp-json/wp-abilities/v1/categories

5) Consume in JavaScript

import { store, useAbility } from '@wordpress/abilities';

// Check if user has ability
const canExport = useAbility('my-plugin/can-export');

if (canExport) {
    // Show export button
}

6) Meta options

Option	Purpose
`readonly`	If true, ability is informational only
`show_in_rest`	If true, exposed via REST API
`default`	Default value for the ability

Verification

REST check: wp-abilities/v1/abilities returns your ability
PHP check: current_user_has_ability() returns expected value
JS check: useAbility() returns expected value

# Test REST endpoint
curl -X GET "https://example.com/wp-json/wp-abilities/v1/abilities" \
  -H "Authorization: Bearer YOUR_TOKEN"

Failure modes / debugging

Ability never appears:

Registration code not running (wrong hook / file not loaded)
Missing meta.show_in_rest
Incorrect category/ID mismatch

REST shows ability but JS doesn't:

Wrong REST base/namespace
JS dependency not bundled
Caching (object/page caches) masking changes

Debug checklist:

# Check if ability is registered
wp eval 'print_r(wp_get_abilities());'

# Check REST endpoint directly
wp rest get /wp-abilities/v1/abilities

Escalation

If version support is unclear:

Confirm target WP core versions
Check if Abilities API is in core or requires plugin

Consult:

Abilities API Core Proposal
WordPress Developer Resources

wp-abilities-api

Install Skill

SKILL.md