Wp Abilities API

WordPressOfficialPublished by WordPress

Skill
Tool integration
Software development
GPL-2.0-or-later
No issues found

From the author

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.

— the description by WordPress

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to working with the WordPress Abilities API. It covers the registration of abilities and categories in PHP, exposing them via the REST API, and consuming them in JavaScript using @wordpress/abilities. The documentation emphasizes a layered architecture—distinguishing between domain capabilities and their projections—to ensure stable, transport-neutral plugin contracts that remain maintainable as consumer requirements evolve.

What it does

Registers abilities and categories using the WordPress Abilities API.
Exposes domain capabilities through the REST API for client consumption.
Provides patterns for delegating ability execution to existing REST controllers.
Offers guidance on grouping heuristics to avoid atomic-ability bloat.
Defines standard error vocabulary for consistent agent-based error handling.
Facilitates client-side ability consumption via @wordpress/abilities.

When to use it

When adding new capabilities that should be discoverable by agents or external clients.
When refactoring existing REST endpoints into a more stable, action-oriented ability contract.
When building features that require consistent permission checks across different transport layers.
When debugging issues where abilities are not appearing in REST responses or client-side registries.

Advantages

Promotes a stable, transport-neutral domain layer that survives UI or consumer changes.
Reduces boilerplate by providing patterns for delegating to existing controller logic.
Ensures consistent error handling and input validation across the plugin ecosystem.
Improves discoverability of plugin actions for AI agents and automated workflows.

Usage examples

“Register a new ability for listing user orders in my plugin.”: The agent will guide you through defining the ability ID, category, and meta, ensuring it is registered via the correct hooks and exposed in the REST API.
“My ability is not showing up in the REST API; how do I debug this?”: The agent will help you verify the registration hook, check for the show_in_rest meta flag, and confirm the namespace and route configuration.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/wordpress/wp-abilities-api/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip wp-abilities-api.zip -d .agents/skills

Documentation by WordPress

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

Before deciding what to register, read references/domain-vs-projection.md — abilities live at the domain capability layer; MCP / Command Palette / REST exposure is a projection. Registration shape and exposure shape are different decisions, and conflating them forces re-registration every time a consumer's constraints change.

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)

For grouping decisions (how many abilities to register, and where to put filters vs. new ability names), read references/grouping-heuristic.md first — it keeps you from shipping one atomic ability per REST operation.

To avoid drift between the ability and the existing UI / REST code path, see references/shared-core-service.md — abilities, REST handlers, CLI commands, and UI controllers should be thin adapters over a shared service. The reference also covers the metric trap (REST handlers that emit usage telemetry) and the AGENTS.md rule for keeping registrations in sync when underlying code paths change.

For shared helper patterns when multiple execute callbacks delegate to existing REST controllers, see references/plugin-family-patterns.md (identify the shared-API-client vs zero-arg-controllers shape) and references/delegate-helper-pattern.md (one helper shape that works, and when not to use it).

For standardized WP_Error codes that let agents reason about retry vs. escalation, see references/error-code-vocabulary.md.

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.
Execute callback returns unexpected errors or silently ignores input:
- input_schema defaults aren't being applied, pagination key drift between the ability and the backing, or empty()-based ID validation — see references/input-schema-gotchas.md.

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

Files

ATTRIBUTION.mdAdded by AutoGineer896 B
LICENSELicence file added by AutoGineer750 B
SKILL.md5.2 KiB
references/delegate-helper-pattern.md12.2 KiB
references/domain-vs-projection.md8.9 KiB
references/error-code-vocabulary.md7.0 KiB
references/grouping-heuristic.md8.5 KiB
references/input-schema-gotchas.md12.9 KiB
references/php-registration.md6.4 KiB
references/plugin-family-patterns.md11.7 KiB
references/rest-api.md378 B
references/shared-core-service.md14.8 KiB

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:

wp_abilities_api_categories_init — Register categories here first.
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',
        'permission_callback' => 'my_plugin_get_info_permissions',
        'meta'                => [
            'show_in_rest' => true,
            'mcp'          => [
                'public' => true, // Expose via the bundled WordPress MCP adapter.
            ],
            'annotations'  => [
                'readonly'    => true,
                'destructive' => false,
                'idempotent'  => true,
            ],
        ],
    ] );
} );

Common primitives

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

Key arguments for `wp_register_ability()`

Argument	Required?	Description
`label`	Required	Human-readable name for UI (e.g., command palette).
`description`	Required	What the ability does.
`category`	Required	Category ID (must be registered first via `wp_abilities_api_categories_init`).
`execute_callback`	Required	Function that runs when the ability is invoked. Receives mixed input (per `input_schema`), returns mixed result or `WP_Error`.
`permission_callback`	Required	Function that checks whether the current user may execute. Receives the same mixed input as `execute_callback`; returns `bool` or `WP_Error`. WP core throws `InvalidArgumentException` if this is missing — there is no implicit default.
`input_schema`	Optional	JSON Schema for expected input (enables validation). Required when the ability accepts input.
`output_schema`	Optional	JSON Schema for returned output (enables validation of the result).
`meta.show_in_rest`	Optional (default `false`)	Set `true` to expose via the `wp-abilities/v1` REST API namespace.
`meta.mcp.public`	Optional (default `false`)	Set `true` to expose the ability as a tool via the bundled WordPress MCP adapter. Independent from `show_in_rest`.
`meta.mcp.type`	Optional (default `'tool'`)	One of `'tool'`, `'resource'`, `'prompt'`. Controls how the bundled MCP adapter projects the ability. Values outside this enum silently coerce to `'tool'`.
`meta.annotations.readonly`	Strongly recommended (default `null`)	`true` if the ability does not modify its environment.
`meta.annotations.destructive`	Strongly recommended (default `null`)	`true` if the ability may perform destructive updates. `false` for additive-only updates.
`meta.annotations.idempotent`	Strongly recommended (default `null`)	`true` if calling the ability repeatedly with the same arguments has no additional effect.

The three annotations under meta.annotations are hints for tooling and documentation — core does not enforce them at runtime, so a missing or null value is silently legal. That permissiveness is exactly why every registration should populate them explicitly: MCP / Command Palette / agent surfaces and review tooling reason about ability safety from these values without invoking the callback. A readonly: null ability is treated as "behavior unknown," which is a worse signal than either true or false. Treat the absence of an annotation as a bug, not a default.

`show_in_rest` vs `mcp.public` — they target different surfaces

These two meta keys answer different questions and do not imply each other:

show_in_rest controls visibility on the WordPress core REST namespace wp-abilities/v1 (the abilities REST API). Clients that talk to that namespace see the ability iff this is true.
mcp.public is read by the bundled WordPress MCP adapter package. The adapter's default MCP server only surfaces abilities whose meta.mcp.public is strictly true. Without it, the ability is registered but invisible to MCP clients connecting through that adapter.

A plugin can set both, either, or neither. If you want the ability discoverable to agents through MCP, set mcp.public => true. If you also want it on the abilities REST namespace (for tooling that talks to wp-abilities/v1 directly), set show_in_rest => true. The two surfaces are independent.

Recommended patterns

Namespace ability IDs as <plugin-slug>/<verb-noun> (e.g., my-plugin/get-info, my-plugin/update-thing). Slash-separated.
Treat IDs as stable API; changing an ID is a breaking change for any consumer that holds a reference.
Use input_schema and output_schema for validation and to help AI agents understand usage.
Always include a permission_callback. It is required on every registration — there is no implicit default.
Always set all three meta.annotations keys (readonly, destructive, idempotent) explicitly. Leaving them at the null default broadcasts "behavior unknown" to every consumer that reads this metadata before invoking the ability. The cost of writing them is three lines; the cost of omitting them is opaque safety surface.

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/
WordPress MCP adapter package — source of meta.mcp.public / meta.mcp.type contract. The adapter ships as a packaged dependency; verify the meta-key names against the package version your plugin pulls in.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

The author says: Targets WordPress 7.0+ (PHP 7.4.0+). Filesystem-based agent with bash + node. Some workflows require WP-CLI.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

WordPress

Publisher

WordPress (Official)

Source

WordPress/agent-skills · skills/wp-abilities-api · commit 7374e6f

Licence

GNU General Public License v2.0 or later (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by WordPress.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download wp-abilities-api.zip