Wp Abilities Api

1---2name: wp-abilities-api3description: "Use when working with the WordPress Abilities API (wp_register_ability, wp_register_ability_category, /wp-json/wp-abilities/v1/*, @wordpress/abilities) including defining abilities, categories, meta, REST exposure, and permissions checks for clients."4compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."5---6 7# WP Abilities API8 9## When to use10 11Use this skill when the task involves:12 13- registering abilities or ability categories in PHP,14- exposing abilities to clients via REST (`wp-abilities/v1`),15- consuming abilities in JS (notably `@wordpress/abilities`),16- diagnosing “ability doesn’t show up” / “client can’t see ability” / “REST returns empty”.17 18## Inputs required19 20- Repo root (run `wp-project-triage` first if you haven’t).21- Target WordPress version(s) and whether this is WP core or a plugin/theme.22- Where the change should live (plugin vs theme vs mu-plugin).23 24## Procedure25 26### 1) Confirm availability and version constraints27 28- If this is WP core work, check `signals.isWpCoreCheckout` and `versions.wordpress.core`.29- If the project targets WP < 6.9, you may need the Abilities API plugin/package rather than relying on core.30 31### 2) Find existing Abilities usage32 33Search for these in the repo:34 35- `wp_register_ability(`36- `wp_register_ability_category(`37- `wp_abilities_api_init`38- `wp_abilities_api_categories_init`39- `wp-abilities/v1`40- `@wordpress/abilities`41 42If none exist, decide whether you’re introducing Abilities API fresh (new registrations + client consumption) or only consuming.43 44### 3) Register categories (optional)45 46If you need a logical grouping, register an ability category early (see `references/php-registration.md`).47 48### 4) Register abilities (PHP)49 50Implement the ability in PHP registration with:51 52- stable `id` (namespaced),53- `label`/`description`,54- `category`,55- `meta`:56  - add `readonly: true` when the ability is informational,57  - set `show_in_rest: true` for abilities you want visible to clients.58 59Use the documented init hooks for Abilities API registration so they load at the right time (see `references/php-registration.md`).60 61### 5) Confirm REST exposure62 63- Verify the REST endpoints exist and return expected results (see `references/rest-api.md`).64- If the client still can’t see the ability, confirm `meta.show_in_rest` is enabled and you’re querying the right endpoint.65 66### 6) Consume from JS (if needed)67 68- Prefer `@wordpress/abilities` APIs for client-side access and checks.69- Ensure build tooling includes the dependency and the project’s build pipeline bundles it.70 71## Verification72 73- `wp-project-triage` indicates `signals.usesAbilitiesApi: true` after your change (if applicable).74- REST check (in a WP environment): endpoints under `wp-abilities/v1` return your ability and category when expected.75- If the repo has tests, add/update coverage near:76  - PHP: ability registration and meta exposure77  - JS: ability consumption and UI gating78 79## Failure modes / debugging80 81- Ability never appears:82  - registration code not running (wrong hook / file not loaded),83  - missing `meta.show_in_rest`,84  - incorrect category/ID mismatch.85- REST shows ability but JS doesn’t:86  - wrong REST base/namespace,87  - JS dependency not bundled,88  - caching (object/page caches) masking changes.89 90## Escalation91 92- If you’re uncertain about version support, confirm target WP core versions and whether Abilities API is expected from core or as a plugin.93- For canonical details, consult:94  - `references/rest-api.md`95  - `references/php-registration.md`