WordPress Abilities API Documentation

Overview

Provide intelligent documentation retrieval for the WordPress Abilities API when building WordPress plugins and applications. The WordPress Abilities API provides a standardized framework for registering, discovering, and executing discrete units of functionality (abilities) in WordPress, with built-in support for REST API exposure, JavaScript client integration, permissions, validation, and extensibility.

This skill automatically fetches relevant documentation from bundled markdown files and provides context-aware routing to ensure users get the right information format for their query.

Activation

Automatically Activate When:

1. WordPress Abilities API Functions Mentioned:

   • Registration: wp_register_ability, wp_register_ability_category
   • Retrieval: wp_get_ability, wp_get_abilities, wp_get_ability_category, wp_get_ability_categories
   • Execution: execute, execute_callback, check_permissions
   • Validation: wp_has_ability, input_schema, output_schema

2. WordPress Abilities API Terms:

   • "Abilities API", "WordPress Abilities", "WP Abilities"
   • "ability registration", "ability categories"
   • "@wordpress/abilities" (JavaScript package)
   • "wp-abilities/v1" (REST API namespace)
   • Ability-related classes, callbacks, schemas

3. File Context Detection:

   • Files with wp_register_ability or wp_register_ability_category calls
   • Imports from @wordpress/abilities
   • REST API calls to /wp-abilities/v1/
   • WordPress plugin files mentioning abilities

4. Implementation Queries:

   • Building WordPress plugins with abilities
   • Registering custom abilities or categories
   • Creating JavaScript clients for abilities
   • Implementing permission callbacks or validation
   • Exposing abilities via REST API

Do NOT Activate For:

• Generic WordPress plugin development without abilities context
• Other WordPress APIs (REST API, Settings API, etc.) unless specifically abilities-related
• Generic JavaScript/REST API discussions without WordPress Abilities context
• WordPress hooks unless specifically ability action/filter hooks

Core Capabilities

1. Context-Aware Documentation Routing

Route queries intelligently based on intent to provide the most useful documentation format:

Route 1: Implementation Queries → Getting Started + Relevant API

Triggers:

• "how to...", "how do I...", "how can I..."
• "build a...", "create a...", "implement..."
• "register an ability", "execute an ability"
• "example of...", "show me how..."

Action:

1. Identify the relevant API area from INDEX.md
2. Read getting-started guide: references/getting-started/[guide].md
3. Read related API documentation: references/[api-type]/[topic].md
4. Include overview context if needed: references/overview/intro.md
5. Present with implementation pattern and code examples

Example Query: "How do I register an ability with input validation?" Fetch:

• references/getting-started/basic-usage.md
• references/php-api/registering-abilities.md
• references/php-api/error-handling.md

Route 2: API Reference Queries → Specific API Documentation

Triggers:

• "what is...", "what does... do"
• "what parameters...", "what arguments..."
• "how does... work"
• "wp_register_ability parameters", "ability schema..."

Action:

1. Look up function/feature in INDEX.md
2. Read single API documentation file: references/[api-type]/[topic].md
3. Suggest 2-3 related functions/features from same category

Example Query: "What parameters does wp_register_ability accept?" Fetch:

• references/php-api/registering-abilities.md Suggest: Using abilities, Categories, Error handling (same category)

Route 3: Getting Started Queries → Installation + Basic Usage

Triggers:

• "getting started with Abilities API"
• "how to install...", "setup..."
• "first ability", "quick start..."
• "new to Abilities API"

Action:

1. Read getting started documentation:
   • references/getting-started/installation.md
   • references/getting-started/basic-usage.md
2. Optionally read references/overview/intro.md for context

Example Query: "I'm new to the Abilities API, how do I get started?" Fetch:

• references/getting-started/installation.md
• references/getting-started/basic-usage.md
• references/overview/intro.md

Route 4: Category/API Type Queries → README + Specific Docs

Triggers:

• "PHP functions for abilities"
• "JavaScript client methods"
• "REST API endpoints"
• "what hooks are available"
• "show me all... functions"

Action:

1. Read references/README.md (contains categorized function/endpoint lists)
2. Read 1-2 key documentation files in that category
3. List all relevant functions/endpoints with brief descriptions from INDEX.md

Example Query: "What JavaScript functions are available for abilities?" Fetch:

• references/README.md
• references/javascript-client/overview.md
• references/javascript-client/abilities.md

Route 5: Integration Queries → Multiple API Types

Triggers:

• "use abilities from JavaScript"
• "REST API and PHP together"
• "client-side and server-side"
• "integrate with..."

Action:

1. Identify relevant API types (PHP, JavaScript, REST)
2. Read overview for each type
3. Read specific implementation guides
4. Show integration pattern

Example Query: "How do I register a PHP ability and execute it from JavaScript?" Fetch:

• references/php-api/registering-abilities.md
• references/javascript-client/abilities.md
• references/rest-api/execution.md

Route 6: Troubleshooting Queries → Error Handling + Relevant Feature

Triggers:

• "error...", "not working...", "failing..."
• "WP_Error...", "validation error..."
• "permission denied", "ability not found"
• "troubleshoot...", "debug..."

Action:

1. Read error handling documentation for relevant API
2. Read specific feature documentation if applicable
3. Reference hooks if extensibility needed

Example Query: "Why am I getting a permission denied error?" Fetch:

• references/php-api/error-handling.md
• references/php-api/using-abilities.md
• references/rest-api/execution.md

2. Smart Multi-Page Fetching

Fetch Multiple Pages (2-4 total) When:

• Implementation queries requiring multiple concepts
• Query mentions multiple APIs (e.g., "PHP and JavaScript")
• Complex workflows (e.g., "register, validate, and execute")
• Related feature sets (registration + execution, categories + abilities)

Fetch Single Page When:

• Simple reference queries
• Troubleshooting lookups
• Single function explanations
• Hook documentation

Stop Fetching When:

• Already fetched 3-4 pages
• Query is answered sufficiently
• Additional pages would be tangential

3. Category-Aware Suggestions

After fetching documentation, always suggest 2-3 related topics using these category groupings:

Overview:

• Introduction, Core concepts, Goals and benefits, Use cases

Getting Started:

• Installation, Basic usage, First ability

PHP API:

• Categories (register, unregister, retrieve)
• Registering Abilities (wp_register_ability, parameters, conventions)
• Using Abilities (retrieve, execute, check permissions, inspect)
• Error Handling (WP_Error, validation, permissions)

JavaScript Client:

• Overview
• Working with Abilities (getAbilities, getAbility, executeAbility)
• Working with Categories (getAbilityCategories, getAbilityCategory)
• Registration (registerAbility, client-side abilities)
• Error Handling (JavaScript errors, error codes)

REST API:

• Overview (authentication, schema, show_in_rest)
• Abilities Endpoints (list, retrieve)
• Categories Endpoints (list, retrieve)
• Execution (run endpoint, HTTP methods, errors)

Hooks:

• Action Hooks (init, before/after execute)
• Filter Hooks (modify registration args)

Common Feature Pairings:

• wp_register_ability → Using abilities, Categories, Error handling
• Execute → Permissions, Error handling, REST execution
• Categories → Registering abilities, Organization
• JavaScript client → REST API, PHP registration
• Input/output schema → Validation, Error handling
• Permissions → Error handling, REST API authentication
• Hooks → Extensibility, Custom behavior

Suggest topics from:

1. Same category (highest priority)
2. Commonly used together
3. Prerequisites or next steps

4. Code Example Generation

Always include relevant code examples in responses:

PHP Registration:

wp_register_ability( 'my-plugin/get-site-info', array(
    'label'             => 'Get Site Information',
    'description'       => 'Returns basic site information',
    'category'          => 'my-plugin-site-management',  // Dashes only
    'execute_callback'  => function( $input ) {
        return array(
            'name' => get_bloginfo( 'name' ),
            'url'  => get_site_url(),
        );
    },
    'permission_callback' => function() {
        return current_user_can( 'manage_options' );
    },
    'meta' => array(
        'show_in_rest' => true,      // Inside meta array
        'mcp'          => array(
            'public' => true,        // Required for MCP discovery
            'type'   => 'tool',
        ),
    ),
) );

JavaScript Execution:

import { executeAbility } from '@wordpress/abilities';

const result = await executeAbility( 'my-plugin/get-site-info', {
    // input parameters
} );

REST API Call:

GET /wp-json/wp-abilities/v1/my-plugin/get-site-info/run

Prerequisites:

• WordPress 5.0 or later
• PHP 7.4 or later
• Abilities API plugin installed and activated
• Check references/getting-started/installation.md for setup

Response Formats

Single-Page Response Format

I've fetched the [Topic Name] documentation from the WordPress Abilities API.

**Quick Setup:**
[Include installation/setup if relevant to query]

[Full documentation content from file]

---

**Related Topics:**
- **[Topic 1]** - [Brief description of relationship]
- **[Topic 2]** - [Brief description of relationship]
- **[Topic 3]** - [Brief description of relationship]

**Code Example:**
[Include relevant code snippet if applicable]

Multi-Page Response Format

This requires understanding multiple aspects of the Abilities API. I've fetched:

---

## [Topic 1 Name]

**Quick Setup:**
[Include setup code if relevant]

[Full content from file]

---

## [Topic 2 Name]

[Full content from file]

---

## [Topic 3 Name] (if needed)

[Full content from file]

---

**Integration Pattern:**
[2-3 sentences explaining how these concepts work together, referencing examples from the documentation]

**Related Topics:**
- **[Additional Topic]** - [Description]
- **[Tutorial/Guide]** - [Description]

**Complete Example:**
[Include comprehensive code example showing integration]

Implementation Guidance Scope

✅ DO Provide:

1. Code Examples from Documentation

   • Show registration patterns from the docs
   • Reference execution examples
   • Demonstrate permission callbacks

2. Feature Integration Patterns

   • "Categories help organize related abilities"
   • "Use input_schema for automatic validation"
   • "Set show_in_rest: true inside meta array to expose via REST API"
   • "Add mcp.public: true for AI assistant discoverability"
   • "Check external plugin availability with class_exists()"

3. Best Practices from Docs

   • "Follow namespace conventions: plugin-name/ability-name for abilities, plugin-name-category for categories"
   • "Always implement permission_callback for security"
   • "Use WP_Error for error handling with appropriate status codes"
   • "Place show_in_rest and mcp settings inside meta array, not top-level"
   • "Category slugs must use dashes only, never slashes"

4. Setup and Configuration

   • Plugin installation methods
   • Availability checking
   • Hook timing (when to register)

5. Common Patterns

   • Registration during init hooks
   • Error handling with WP_Error
   • Schema validation with JSON Schema
   • Permission checking patterns

6. API Integration Guidance

   • PHP to JavaScript integration
   • REST API authentication
   • Client-side vs server-side execution

❌ DON'T Provide:

1. Custom Implementations Beyond Docs - Only show documented patterns
2. Undocumented Features - Stick to documented capabilities only
3. Complex Plugin Development - Focus on Abilities API usage
4. Debugging Complex User Code - Can reference error handling docs only
5. WordPress Core Development - Only Abilities API specific features

Documentation Access

File Structure

All documentation is bundled in the skill at:

.claude/skills/wp-abilities-api/
├── SKILL.md (this file)
└── references/
    ├── INDEX.md (searchable keyword reference)
    ├── README.md (overview and quick reference)
    ├── overview/
    │   └── intro.md
    ├── getting-started/
    │   ├── installation.md
    │   └── basic-usage.md
    ├── php-api/
    │   ├── categories.md
    │   ├── registering-abilities.md
    │   ├── using-abilities.md
    │   └── error-handling.md
    ├── javascript-client/
    │   ├── overview.md
    │   ├── abilities.md
    │   ├── categories.md
    │   ├── registration.md
    │   └── error-handling.md
    ├── rest-api/
    │   ├── overview.md
    │   ├── abilities-endpoints.md
    │   ├── categories-endpoints.md
    │   └── execution.md
    └── hooks/
        ├── actions.md
        └── filters.md

How to Access Documentation

1. Search INDEX.md for function names, keywords, or categories
2. Read files using the Read tool with absolute paths:
   • PHP API: .claude/skills/wp-abilities-api/references/php-api/[topic].md
   • JavaScript: .claude/skills/wp-abilities-api/references/javascript-client/[topic].md
   • REST API: .claude/skills/wp-abilities-api/references/rest-api/[topic].md
   • Getting Started: .claude/skills/wp-abilities-api/references/getting-started/[topic].md
   • Hooks: .claude/skills/wp-abilities-api/references/hooks/[type].md
3. Extract metadata from INDEX.md entries (keywords, categories)
4. Generate suggestions using category groupings and common pairings

Query Interpretation Examples

Example 1: Implementation Query

Query: "How do I register an ability with input validation?"

Routing: Implementation query → Getting Started + PHP API

Process:

1. Search INDEX.md for "register", "validation", "input_schema"
2. Read references/getting-started/basic-usage.md
3. Read references/php-api/registering-abilities.md
4. Include schema example

Response includes:

• Basic registration pattern
• input_schema parameter with JSON Schema
• Validation error handling
• Related: Error handling, Using abilities

Example 2: API Reference Query

Query: "What parameters does wp_register_ability accept?"

Routing: API reference query → PHP API only

Process:

1. Look up "wp_register_ability" in INDEX.md
2. Read references/php-api/registering-abilities.md
3. Find related: Using abilities, Categories, Error handling

Response includes:

• Complete parameter list and descriptions
• Code examples
• Naming conventions
• Suggestions: Using abilities, Categories, Error handling

Example 3: Getting Started Query

Query: "I'm new to the Abilities API, how do I get started?"

Routing: General guidance → Getting started docs

Process:

1. Read references/overview/intro.md
2. Read references/getting-started/installation.md
3. Read references/getting-started/basic-usage.md

Response includes:

• What the Abilities API is
• Installation instructions
• First ability example
• Next steps

Example 4: Integration Query

Query: "How do I execute a PHP ability from JavaScript?"

Routing: Integration query → Multiple APIs

Process:

1. Read references/php-api/registering-abilities.md (show_in_rest)
2. Read references/javascript-client/abilities.md (executeAbility)
3. Read references/rest-api/execution.md

Response includes:

• PHP registration with show_in_rest: true
• JavaScript executeAbility example
• REST API authentication
• Error handling on both sides

Example 5: Troubleshooting Query

Query: "Why am I getting a WP_Error when executing an ability?"

Routing: Troubleshooting → Error handling + Execution

Process:

1. Read references/php-api/error-handling.md
2. Read references/php-api/using-abilities.md
3. Identify common error patterns

Response includes:

• WP_Error handling patterns
• Common error scenarios (permissions, validation, execution)
• Checking for errors with is_wp_error()
• Related: Permissions, Validation

Common Issues & Quick Fixes

Registration Failures

Issue: Ability not found / "category must contain only lowercase alphanumeric characters and dashes" Fix: Category slug uses slashes → Change to dashes only (my-plugin-content not my-plugin/content)

Issue: "Property 'show_in_rest' is not a valid property" Fix: Move show_in_rest inside meta array, not top-level

Issue: Ability not discoverable via MCP Fix: Add 'mcp' => array('public' => true) inside meta array

Schema Validation Failures

Issue: Output validation fails with "field is not of type X" when field is null Fix: Use array type syntax to allow null: 'type' => array('object', 'null')

Issue: Enum validation fails when field value is empty string Fix: Include empty string in enum: 'enum' => array('option1', 'option2', '')

REST API Issues

Issue: GET request input param not being parsed correctly Fix: Use array-style params (input[post_id]=1) instead of JSON string. POST with JSON body works normally.

WP-CLI Testing

Issue: ability_invalid_permissions error when testing via WP-CLI Fix: Pass --user=admin flag to provide user context for permission checks

External Plugin Integration

When integrating with external plugins, always check availability first:

'execute_callback' => function( $input ) {
    if ( ! class_exists( 'PluginNamespace\Class' ) ) {
        return new WP_Error( 'plugin_not_active', 'Required plugin not active', array( 'status' => 503 ) );
    }
    // Use plugin functionality
},

Correct Meta Structure

'meta' => array(
    'show_in_rest' => true,        // REST API exposure
    'mcp'          => array(
        'public' => true,          // MCP discoverability
        'type'   => 'tool',        // 'tool', 'resource', or 'prompt'
    ),
),

Important Notes

Naming Conventions

Always mention:

• Ability names: plugin-name/ability-name (forward slash after prefix)
• Category slugs: plugin-name-category-name (dashes only, NO slashes)
• Use lowercase with hyphens throughout
• Include plugin/theme prefix for uniqueness

CRITICAL: Category slugs must use dashes only. Forward slashes cause validation errors.

Security

Reference security when appropriate:

• Always implement permission_callback
• Validate and sanitize input
• Use WordPress nonce for AJAX requests
• Follow WordPress security best practices

WordPress Integration

• Register abilities on wp_abilities_api_init or init hooks
• Use wp_abilities_api_categories_init for categories
• Check availability with class_exists( 'WP_Abilities_Registry' )
• Follow WordPress coding standards

REST API & MCP Exposure

REST API:

• Set show_in_rest: true (inside meta array) to expose via REST API
• Consider authentication requirements
• Use readonly annotation for safe GET execution
• Destructive operations require POST

MCP (Model Context Protocol):

• Set mcp.public: true (inside meta array) to make discoverable by AI assistants
• Type options: 'tool' (default), 'resource', 'prompt'
• Only abilities with mcp.public = true are exposed via MCP adapter

Workflow Summary

For every query:

1. Identify intent → Implementation, API reference, getting started, integration, or troubleshooting
2. Route appropriately → Determine which files to fetch
3. Search INDEX.md → Find relevant functions, keywords, categories
4. Read files → Use Read tool to access documentation
5. Format response → Include code examples, content, integration patterns, suggestions
6. Suggest related → Use category groupings and common pairings

Keep responses:

• Focused on documented information
• Formatted with clear code examples
• Enriched with relevant topic suggestions
• Practical with setup and usage guidance
• Security-conscious with permission reminders