gh-emdashcodes-wp-ability-toolkit-claude-code-plugins-wordpress-ability-api/skills/wordpress-ability-api/references/7.registering-categories.md

7. Registering Categories

Before registering abilities, you must register at least one category. Categories help organize abilities and make them easier to discover and filter.

Function Signature

wp_register_ability_category( string $slug, array $args ): ?\WP_Ability_Category

Parameters:

• $slug (string): A unique identifier for the category. Must contain only lowercase alphanumeric characters and dashes (no underscores, no uppercase).
• $args (array): Category configuration with these keys:
  • label (string, Required): Human-readable name for the category. Should be translatable.
  • description (string, Required): Detailed description of the category's purpose. Should be translatable.
  • meta (array, Optional): An associative array for storing arbitrary additional metadata about the category.

Return: (?\WP_Ability_Category) An instance of the registered category if it was successfully registered, null on failure (e.g., invalid arguments, duplicate slug).

Note: Categories must be registered during the abilities_api_categories_init action hook.

Code Example

add_action( 'abilities_api_categories_init', 'my_plugin_register_categories' );
function my_plugin_register_categories() {
    wp_register_ability_category( 'data-retrieval', array(
        'label' => __( 'Data Retrieval', 'my-plugin' ),
        'description' => __( 'Abilities that retrieve and return data from the WordPress site.', 'my-plugin' ),
    ));

    wp_register_ability_category( 'data-modification', array(
        'label' => __( 'Data Modification', 'my-plugin' ),
        'description' => __( 'Abilities that modify data on the WordPress site.', 'my-plugin' ),
    ));

    wp_register_ability_category( 'communication', array(
        'label' => __( 'Communication', 'my-plugin' ),
        'description' => __( 'Abilities that send messages or notifications.', 'my-plugin' ),
    ));
}

Category Slug Convention

The $slug parameter must follow these rules:

• Format: Must contain only lowercase alphanumeric characters (a-z, 0-9) and hyphens (-).
• Valid examples: data-retrieval, ecommerce, site-information, user-management, category-123
• Invalid examples:
  • Uppercase: Data-Retrieval, MyCategory
  • Underscores: data_retrieval
  • Special characters: data.retrieval, data/retrieval, data retrieval
  • Leading/trailing dashes: -data, data-
  • Double dashes: data--retrieval

Other Category Functions

• wp_unregister_ability_category( string $slug ) - Remove a registered category. Returns the unregistered category instance or null on failure.
• wp_get_ability_category( string $slug ) - Retrieve a specific category by slug. Returns the category instance or null if not found.
• wp_get_ability_categories() - Get all registered categories as an associative array keyed by slug.