superpowers-sage:abilities-authoring

abilities-authoring — WordPress MCP Abilities

An Ability exposes a callable MCP endpoint via the WordPress MCP Adapter. Claude calls it via execute-ability after discover-abilities lists it.

Anatomy of an Ability

class ListProjectsAbility extends Ability
{
    public string $name = 'projects/list';
    public string $description = 'Return all published Project CPT posts.';
    public array $schema = [ /* JSON Schema for input */ ];

    public function execute(array $args): array
    {
        // returns array — serialized as JSON by the adapter
    }
}

Creating an Ability

lando wp acorn make:ability <Name>
# Example: lando wp acorn make:ability ListProjects
# Creates: app/Abilities/ListProjectsAbility.php

Use templates in assets/ability-*.php.tpl for query, CRUD, and search patterns.

Registration

In app/Providers/AbilitiesServiceProvider.php:

use App\Abilities\ListProjectsAbility;

public function boot(): void
{
    $this->app->make(AbilityRegistry::class)->register([
        new ListProjectsAbility(),
    ]);
}

See references/registration.md for full ServiceProvider setup.

JSON Schema

The $schema array follows JSON Schema Draft-07. See references/schema.md.

MCP exposure

For an Ability to appear in discover-abilities, the MCP Adapter must be running. See references/mcp-exposure.md.

Common patterns

See references/patterns.md for query, CRUD, search, ACF field groups, and Livewire components patterns.

Verification

bash scripts/list-abilities.sh

Then in your Claude Code session: call discover-abilities — the Ability should appear.

Failure modes

Problem: Ability not appearing in discover-abilities

• Cause: The Ability is not registered in AbilitiesServiceProvider, or the service provider is not in config/app.php providers array.
• Fix: Verify the Ability class is added to AbilityRegistry::register() in the service provider. Check that the provider is listed in config/app.php and is actually being booted. Claude Code caches discover-abilities — restart the editor after registration changes.