wp-abilities-api

SKILL.md

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