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.
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.
| 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/abilitiesreturns 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