wp-abilities-api

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.

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 2, 2026

When & Why to Use This Skill

This Claude skill facilitates the seamless integration and management of the WordPress Abilities API. It provides expert guidance on registering abilities and categories in PHP, exposing them via REST API endpoints, and consuming them in JavaScript using the @wordpress/abilities package, ensuring robust and synchronized permission checks across the entire WordPress stack.

Use Cases

  • Registering custom feature flags and permission categories within WordPress plugins or themes to manage granular user access.
  • Exposing backend PHP-defined abilities to frontend React components or Gutenberg blocks via the /wp-json/wp-abilities/v1/ REST endpoint.
  • Implementing conditional UI rendering in modern WordPress dashboards based on real-time user ability checks using the useAbility hook.
  • Troubleshooting and diagnosing registration hook failures or REST API visibility issues when abilities fail to appear in the client-side state.
namewp-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: