Wp Abilities Api

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 (notably @wordpress/abilities),
• diagnosing “ability doesn’t show up” / “client can’t see ability” / “REST returns empty”.

Inputs required

• Repo root (run wp-project-triage first if you haven’t).
• Target WordPress version(s) and whether this is WP core or a plugin/theme.
• Where the change should live (plugin vs theme vs mu-plugin).

Procedure

1) Confirm availability and version constraints

• If this is WP core work, check signals.isWpCoreCheckout and versions.wordpress.core.
• If the project targets WP < 6.9, you may need the Abilities API plugin/package rather than relying on core.

2) Find existing Abilities usage

Search for these in the repo:

• wp_register_ability(
• wp_register_ability_category(
• wp_abilities_api_init
• wp_abilities_api_categories_init
• wp-abilities/v1
• @wordpress/abilities

If none exist, decide whether you’re introducing Abilities API fresh (new registrations + client consumption) or only consuming.

3) Register categories (optional)

If you need a logical grouping, register an ability category early (see references/php-registration.md).

4) Register abilities (PHP)

Implement the ability in PHP registration with:

• stable id (namespaced),
• label/description,
• category,
• meta:
• add readonly: true when the ability is informational,
• set show_in_rest: true for abilities you want visible to clients.

Use the documented init hooks for Abilities API registration so they load at the right time (see references/php-registration.md).

5) Confirm REST exposure

• Verify the REST endpoints exist and return expected results (see references/rest-api.md).
• If the client still can’t see the ability, confirm meta.show_in_rest is enabled and you’re querying the right endpoint.

6) Consume from JS (if needed)

• Prefer @wordpress/abilities APIs for client-side access and checks.
• Ensure build tooling includes the dependency and the project’s build pipeline bundles it.

Verification

• wp-project-triage indicates signals.usesAbilitiesApi: true after your change (if applicable).
• REST check (in a WP environment): endpoints under wp-abilities/v1 return your ability and category when expected.
• If the repo has tests, add/update coverage near:
• PHP: ability registration and meta exposure
• JS: ability consumption and UI gating

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.

Escalation

• If you’re uncertain about version support, confirm target WP core versions and whether Abilities API is expected from core or as a plugin.
• For canonical details, consult:
• references/rest-api.md
• references/php-registration.md

PHP registration quick guide

Key concepts and entrypoints for the WordPress Abilities API:

• Register ability categories and abilities in PHP.
• Use the Abilities API init hooks to ensure registration occurs at the right lifecycle time.

Hook order (critical)

Categories must be registered before abilities. Use the correct hooks:

1. wp_abilities_api_categories_init — Register categories here first. 2. wp_abilities_api_init — Register abilities here (after categories exist).

Warning: Registering abilities outside wp_abilities_api_init triggers _doing_it_wrong() and the registration will fail.

// 1. Register category first
add_action( 'wp_abilities_api_categories_init', function() {
    wp_register_ability_category( 'my-plugin', [
        'label' => __( 'My Plugin', 'my-plugin' ),
    ] );
} );

// 2. Then register abilities
add_action( 'wp_abilities_api_init', function() {
    wp_register_ability( 'my-plugin/get-info', [
        'label'       => __( 'Get Site Info', 'my-plugin' ),
        'description' => __( 'Returns basic site information.', 'my-plugin' ),
        'category'    => 'my-plugin',
        'execute_callback' => 'my_plugin_get_info_callback',
        'meta'        => [ 'show_in_rest' => true ],
    ] );
} );

Common primitives

• wp_register_ability_category( $category_id, $args )
• wp_register_ability( $ability_id, $args )

Key arguments for wp_register_ability()

Recommended patterns

• Namespace IDs (e.g. my-plugin:feature.edit).
• Treat IDs as stable API; changing IDs is a breaking change.
• Use input_schema and output_schema for validation and to help AI agents understand usage.
• Always include a permission_callback for abilities that modify data.

References

• Abilities API handbook: https://developer.wordpress.org/apis/abilities-api/
• Dev note: https://make.wordpress.org/core/2025/11/10/abilities-api-in-wordpress-6-9/

REST API quick guide (wp-abilities/v1)

The Abilities API exposes endpoints under the REST namespace:

• wp-abilities/v1/abilities
• wp-abilities/v1/categories

Debug checklist:

• Confirm the route exists under wp-json/wp-abilities/v1/....
• Verify the ability/category shows in REST responses.
• If missing, confirm meta.show_in_rest is enabled for that ability.