Wp Abilities Api
Register WordPress abilities and categories, expose them on wp-abilities/v1 REST, and wire @wordpress/abilities clients with correct permissions.
Overview
wp-abilities-api is an agent skill for the Build phase that registers WordPress abilities and categories, exposes them via REST, and aligns @wordpress/abilities clients with permission checks.
Install
npx skills add https://github.com/wordpress/agent-skills --skill wp-abilities-apiWhat is this skill?
- Covers wp_register_ability, wp_register_ability_category, and wp_abilities_api_init lifecycle hooks
- Documents REST consumption at /wp-json/wp-abilities/v1/* for agent and block clients
- Guides @wordpress/abilities JS usage alongside server-side registration
- Includes triage flow: repo root, WP version ≥6.9 vs plugin package, plugin vs theme vs mu-plugin placement
- Diagnostic patterns for abilities missing from REST, empty responses, and permission failures
- Targets WordPress 6.9+ (PHP 7.2.24+)
- REST namespace wp-abilities/v1
Adoption & trust: 1.4k installs on skills.sh; 1.6k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your WordPress agent or block client cannot discover or invoke abilities because registration, REST routes, or permissions were never aligned with Abilities API conventions.
Who is it for?
WordPress plugin or theme authors targeting WP 6.9+ who want agent-callable abilities without reverse-engineering core from scratch.
Skip if: Non-WordPress stacks, sites locked below 6.9 without adopting the Abilities API package, or tasks that only need generic REST CRUD unrelated to abilities.
When should I use this skill?
The task involves registering abilities or categories, exposing wp-abilities/v1, consuming @wordpress/abilities, or diagnosing missing REST abilities.
What do I get? / Deliverables
Abilities and categories register on the correct hooks, appear under wp-abilities/v1 where permitted, and JS clients can consume them with diagnosable failure modes.
- Registered ability and category definitions
- REST-visible ability entries with permission callbacks
- JS client integration notes for @wordpress/abilities
Recommended Skills
Journey fit
Abilities API work is integration engineering on WordPress—canonical placement is Build because you are extending core/plugin surfaces agents and apps call. Integrations subphase fits PHP registration hooks, REST routes, and JS client consumption rather than pure theme UI.
How it compares
WordPress-native ability registry skill—not a generic OpenAPI generator or unrelated MCP bridge.
Common Questions / FAQ
Who is wp-abilities-api for?
Solo WordPress developers and indie plugin authors wiring agent-visible abilities for REST and @wordpress/abilities clients on modern core versions.
When should I use wp-abilities-api?
During Build integrations when registering wp_register_ability, exposing wp-abilities/v1, or debugging why an ability is invisible to REST consumers.
Is wp-abilities-api safe to install?
It describes PHP and WP-CLI filesystem work that can change production plugins—review the Security Audits panel on this page and test on staging first.
Workflow Chain
Requires first: wp project triage
SKILL.md
READMESKILL.md - 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` # 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 abilit