Wp Abilities API

1---
2name: wp-abilities-api
3description: "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 API
8 
9## When to use
10 
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 required
19 
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## Procedure
25 
26### 1) Confirm availability and version constraints
27 
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 usage
32 
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 exposure
62 
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## Verification
72 
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 exposure
77  - JS: ability consumption and UI gating
78 
79## Failure modes / debugging
80 
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## Escalation
91 
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`
96