Il cambio di mentalità necessario è piccolo ma potente. Oggi la maggior parte dei plugin SEO fa il proprio audit chiamando Yoast o Rank Math via reflection o hook, con risultati fragili e duplicazione di logica. Con Abilities API, ogni plugin espone le proprie capacità come abilities registrate, e chiunque può chiederle via wp_get_ability() con capability check, audit log e kill switch integrati. Questo non è teorico: il Plugin Team stesso lo usa già per i triage AI del Plugin Directory 2026.

Per capire il contesto AI dell'API rimando al pattern ufficiale Plugin Team MCP + Abilities e alla preparazione alla AI-use disclosure; qui il focus è su come chiunque può adottare Abilities API anche senza una sola riga di codice AI, ottenendo vantaggi concreti in robustezza, auditabilità e interoperabilità tra plugin.

Cos'è Abilities API WordPress 6.9 in 90 secondi

Abilities API è una nuova API core di WordPress 6.9 che permette a un plugin (o al core) di registrare "abilità" (abilities) come unità discrete di funzionalità. Ogni ability ha:

• Slug univoco: seo-audit/canonical-check, security-scan/file-integrity, performance-check/db-query-time
• Capability requirements: chi può chiamarla (administrator, editor, custom role)
• Input schema: parametri accettati (post_id, capability array, scope)
• Output schema: struttura del risultato atteso
• Callback registrato: la funzione che esegue l'abilità
• Audit metadata: chi l'ha chiamata, quando, con quali parametri

A differenza degli hook tradizionali, un'ability è una funzione chiamabile esplicitamente da altro codice con un'API uniforme, non un side effect agganciato a un evento. Questo la rende perfetta per audit e check operativi, dove serve un "contratto" chiaro tra chi chiede e chi esegue.

Differenza tra Ability e Hook WordPress

Un hook tradizionale (do_action, apply_filters) è publish-subscribe: il publisher non sa chi ascolta. Un'ability è request-response: il chiamante sa esattamente cosa sta chiedendo e cosa riceverà. Questa differenza sembra sottile ma in termini di testabilità, documentazione e debug è enorme.

Differenza tra Ability e REST endpoint

Un'ability è simile a un REST endpoint ma vive nello stesso processo PHP, senza HTTP overhead. È ideale per uso server-side (WP-CLI, cron, plugin-to-plugin). Per uso client-side (JavaScript in admin) si consiglia di esporre l'ability anche via REST controller aggiuntivo.

Caso d'uso 1: audit SEO come abilities componibili

Vediamo il primo caso d'uso pratico: trasformare i 12 check SEO che ogni agenzia fa a mano (canonical, meta description, alt text, structured data, robots, sitemap, ecc.) in abilities dichiarate. Il vantaggio immediato è che qualunque plugin (Rank Math, Yoast, SEOPress) può esporre le proprie check come abilities, e i tool di audit (WooCommerce, page builder, plugin custom) possono chiamarle senza dover conoscere il plugin specifico.

Registrazione di un'ability SEO canonical-check

// registra un'ability SEO audit
add_action( 'wp_abilities_api_init', function() {
    wp_register_ability( 'seo-audit/canonical-check', array(
        'label'       => __( 'Canonical URL check', 'seo-abilities' ),
        'description' => __( 'Verifica che il post abbia un canonical URL valido', 'seo-abilities' ),
        'callback'    => 'seo_abilities_check_canonical',
        'capability'  => 'edit_posts',
        'input_schema' => array(
            'type'       => 'object',
            'properties' => array(
                'post_id' => array( 'type' => 'integer' )
            ),
            'required'   => array( 'post_id' )
        ),
        'output_schema' => array(
            'type'       => 'object',
            'properties' => array(
                'has_canonical' => array( 'type' => 'boolean' ),
                'canonical_url' => array( 'type' => 'string' ),
                'is_self'       => array( 'type' => 'boolean' ),
                'severity'      => array( 'type' => 'string' )
            )
        )
    ) );
} );

function seo_abilities_check_canonical( $input ) {
    $post = get_post( $input['post_id'] );
    if ( ! $post ) {
        return new WP_Error( 'post_not_found', __( 'Post non trovato', 'seo-abilities' ) );
    }
    $canonical = get_permalink( $post->ID );
    return array(
        'has_canonical' => true,
        'canonical_url' => $canonical,
        'is_self'       => true,
        'severity'      => 'ok'
    );
}

Composizione di più abilities per audit completo

// chiama 5 abilities SEO in sequenza e aggrega risultati
function seo_abilities_full_audit( $post_id ) {
    $checks = array(
        'seo-audit/canonical-check',
        'seo-audit/meta-description-check',
        'seo-audit/alt-text-check',
        'seo-audit/structured-data-check',
        'seo-audit/robots-meta-check'
    );
    $report = array();
    foreach ( $checks as $slug ) {
        $ability = wp_get_ability( $slug );
        if ( $ability && current_user_can( $ability->capability ) ) {
            $report[ $slug ] = $ability->callback( array( 'post_id' => $post_id ) );
        }
    }
    return $report;
}

Vantaggio rispetto a Rank Math standalone

Rank Math ha già le proprie funzioni interne di audit, ma sono sealed. Esponendole come abilities, chiunque può scrivere un tool che le chiama via API pubblica, senza reflection. Inoltre un'agenzia può costruire un proprio tool centralizzato che gira seo-audit/full-audit su tutti i 50 siti del cliente, aggregando i risultati.

Caso d'uso 2: scan di sicurezza come abilities verificabili

Il secondo caso d'uso è la sicurezza. I plugin di sicurezza oggi fanno scan in modi molto diversi tra loro (Wordfence, Sucuri, iThemes, Solid Security), spesso con logica duplicata e audit trail frammentato. Con Abilities API possiamo standardizzare gli scan di base.

Ability file-integrity check

// ability: verifica integrità file core WordPress
add_action( 'wp_abilities_api_init', function() {
    wp_register_ability( 'security-scan/file-integrity', array(
        'label'       => __( 'File integrity check', 'security-abilities' ),
        'description' => __( 'Confronta hash dei file core con signature note', 'security-abilities' ),
        'callback'    => 'security_abilities_check_integrity',
        'capability'  => 'manage_options',
        'input_schema' => array(
            'type'       => 'object',
            'properties' => array(
                'scope' => array( 'type' => 'string', 'enum' => array( 'core', 'plugins', 'themes', 'all' ) )
            )
        ),
        'output_schema' => array(
            'type'       => 'object',
            'properties' => array(
                'modified_files' => array( 'type' => 'array' ),
                'severity'       => array( 'type' => 'string' )
            )
        )
    ) );
} );

function security_abilities_check_integrity( $input ) {
    $scope = $input['scope'] ?? 'core';
    $modified = array();
    // logica di confronto hash semplificata
    $check_root = ABSPATH;
    $iterator = new RecursiveIteratorIterator( new RecursiveDirectoryIterator( $check_root ) );
    foreach ( $iterator as $file ) {
        if ( $file->isFile() && in_array( $file->getExtension(), array( 'php', 'js' ) ) ) {
            $hash = md5_file( $file->getPathname() );
            // confronto con signature store (in produzione: db o file firmato)
            if ( ! security_abilities_hash_known( $file->getPathname(), $hash ) ) {
                $modified[] = str_replace( ABSPATH, '', $file->getPathname() );
            }
        }
    }
    return array(
        'modified_files' => $modified,
        'severity'       => count( $modified ) > 0 ? 'high' : 'ok'
    );
}

Integrazione con WP-CLI per audit massivi

Una volta che le abilities di sicurezza sono registrate, possiamo lanciarle via WP-CLI 2026 su tutti i siti di un multisite o di una flotta gestita:

# audit sicurezza massivo via WP-CLI
wp ability run security-scan/file-integrity --scope=all --format=json
wp ability run security-scan/suspicious-patterns --format=json

Questo tipo di automazione prima richiedeva script personalizzati per ogni plugin di sicurezza; con Abilities API diventa un comando standard.

Caso d'uso 3: check di performance come abilities composite

Il terzo caso d'uso è forse il più sorprendente. I plugin di caching (WP Rocket, LiteSpeed, W3 Total Cache) oggi espongono le proprie metriche in modi proprietari. Con Abilities API possiamo esporre check di performance come abilities standard e creare dashboard cross-plugin.

Ability db-query-time check

// ability: misura tempo medio query database
add_action( 'wp_abilities_api_init', function() {
    wp_register_ability( 'performance-check/db-query-time', array(
        'label'       => __( 'Database query time', 'performance-abilities' ),
        'description' => __( 'Misura tempo medio di esecuzione query DB', 'performance-abilities' ),
        'callback'    => 'performance_abilities_check_db_time',
        'capability'  => 'manage_options',
        'input_schema' => array(
            'type'       => 'object',
            'properties' => array(
                'sample_size' => array( 'type' => 'integer', 'default' => 100 )
            )
        ),
        'output_schema' => array(
            'type'       => 'object',
            'properties' => array(
                'avg_query_time' => array( 'type' => 'number' ),
                'slow_queries'   => array( 'type' => 'integer' ),
                'severity'       => array( 'type' => 'string' )
            )
        )
    ) );
} );

function performance_abilities_check_db_time( $input ) {
    global $wpdb;
    $sample_size = $input['sample_size'] ?? 100;
    $times = array();
    $slow = 0;
    for ( $i = 0; $i < $sample_size; $i++ ) {
        $start = microtime( true );
        $wpdb->get_results( "SELECT ID FROM {$wpdb->posts} WHERE post_status = 'publish' LIMIT 1" );
        $elapsed = microtime( true ) - $start;
        $times[] = $elapsed;
        if ( $elapsed > 0.05 ) $slow++;
    }
    $avg = array_sum( $times ) / count( $times );
    return array(
        'avg_query_time' => round( $avg * 1000, 2 ), // ms
        'slow_queries'   => $slow,
        'severity'       => $avg > 0.03 ? 'high' : ( $avg > 0.01 ? 'medium' : 'ok' )
    );
}

Dashboard cross-plugin che consuma abilities

Un'agenzia può creare un custom admin page che chiama 8-10 abilities (SEO + security + performance) e mostra un report unificato. Il vantaggio è che funziona indipendentemente da quali plugin specifici sono installati, purché espongano le abilities standard.

Capability matrix e governance delle abilities

Una delle funzionalità più potenti di Abilities API è la capability matrix: ogni ability dichiara chi può chiamarla e in quali contesti. Questo apre a scenari di governance che prima erano impossibili.

Matrice capability per ruolo

Custom role per auditor esterno

// crea custom role "site-auditor" con capability granulari
add_role( 'site_auditor', __( 'Site Auditor', 'abilities-governance' ), array(
    'read'                   => true,
    'run_seo_audit'          => true,
    'run_security_scan'      => true,
    'run_performance_check'  => true,
    'edit_posts'             => false
) );

Con questa capability matrix, un'agenzia può dare a un consulente esterno un accesso limitato in sola lettura per auditare 50 siti senza dargli le chiavi del kingdom.

Audit log e tracciabilità

Abilities API prevede un sistema di audit log integrato che registra ogni chiamata. Questo è fondamentale in contesti regolamentati (GDPR, AI Act, NIS2).

Hook per audit log

// registra ogni chiamata ability nel log custom
add_action( 'wp_ability_executed', function( $slug, $input, $output, $user_id ) {
    $log_entry = array(
        'timestamp' => current_time( 'mysql' ),
        'user_id'   => $user_id,
        'ability'   => $slug,
        'input'     => $input,
        'success'   => ! is_wp_error( $output ),
        'ip'        => $_SERVER['REMOTE_ADDR'] ?? ''
    );
    global $wpdb;
    $wpdb->insert( $wpdb->prefix . 'abilities_audit_log', $log_entry );
}, 10, 4 );

Export log per compliance

# esporta audit log per compliance GDPR/AI Act
wp db query "SELECT * FROM wp_abilities_audit_log WHERE timestamp > DATE_SUB(NOW(), INTERVAL 90 DAY) AND ability LIKE 'seo-audit/%'" --format=json > audit_seo_90gg.json

Questo tipo di tracciabilità è esattamente ciò che la AI-use disclosure del Plugin Directory richiede per i plugin AI, ed è applicabile anche a plugin non-AI in contesti enterprise.

Confronto rapido: Abilities API vs approccio tradizionale

Roadmap adozione per agenzia

Ecco come un'agenzia WordPress può adottare Abilities API in 30 giorni:

Settimana 1: aggiorna tutti i siti di sviluppo a WordPress 6.9, identifica le funzionalità ripetitive che fai manualmente (audit SEO, scan sicurezza, check performance) e mappale come abilities potenziali.

Settimana 2: sviluppa un plugin leggero agenzia-abilities-pack con 5-8 abilities custom per i tuoi workflow ricorrenti. Pubblicalo come plugin interno o nel repository.

Settimana 3: integra le abilities nei tuoi tool WP-CLI per audit massivi su tutti i siti clienti. Esempio: wp agenzia audit-all-clients.

Settimana 4: crea una dashboard custom che chiama 10+ abilities via REST (estensione opzionale) per offrire al cliente un report visuale senza esporre l'admin WordPress.

Checklist operativa

Per adottare Abilities API senza errori comuni:

• Aggiorna a WordPress 6.9+ su staging prima di produzione
• Definisci slug standard per le tue abilities (namespace/action-name)
• Documenta ogni ability con input/output schema completi
• Testa sempre capability matrix prima di rilasciare in produzione
• Configura audit log retention secondo policy GDPR (default 90 giorni)
• Monitora performance: troppe abilities chiamate in loop possono rallentare
• Versiona le abilities con prefisso v1/, v2/ per future breaking changes

FAQ su Abilities API WordPress 6.9

Abilities API funziona con WordPress 6.8 e precedenti?

No, è una novità di WordPress 6.9. Per versioni precedenti si può replicare il pattern con classi custom e reflection, ma perde i vantaggi di capability e audit log nativi. Il consiglio è aggiornare a 6.9.

Serve un plugin aggiuntivo per usare le abilities?

No, le API di base (wp_register_ability, wp_get_ability) sono in core 6.9. Plugin aggiuntivi possono aggiungere abilities specifiche (es. un plugin SEO che registra le proprie abilities), ma non sono necessari per l'uso.

Le abilities sostituiscono REST API?

No, sono complementari. Le abilities vivono in-process PHP, REST API vive via HTTP. Per uso server-side (cron, WP-CLI, plugin-to-plugin) usa abilities. Per uso client-side (JavaScript in admin) puoi esporre le abilities anche come REST endpoint aggiuntivi.

Come gestisco abilities che dipendono da plugin di terze parti?

L'ability deve verificare che il plugin sia attivo prima di registrarsi o eseguire il callback. Usa function_exists(), class_exists() o is_plugin_active() come guard. Se la dipendenza manca, restituisci un WP_Error chiaro.

Le abilities sono adatte a siti multisite?

Sì, anzi sono particolarmente utili in multisite perché permettono di centralizzare capability matrix e audit log a livello di network. Una network admin può decidere quali abilities sono disponibili su quali siti del network.

È sicuro esporre abilities sensibili via REST?

Solo se il permission_callback verifica capability. Mai esporre abilities con capability manage_options senza un check lato REST equivalente. Il pattern consigliato è permission_callback => '__return_true' solo dopo current_user_can($ability->capability).

Riferimenti utili per approfondire

• Kinsta: What's new in WordPress 6.9 - panoramica completa delle novità incluse Abilities API con esempi
• WordPress 6.9 release notes ufficiale - changelog dettagliato del rilascio
• GitHub Gutenberg repository Abilities API - source code e PR della API
• Plugin Team: AI triage 2026 (mrtux.it) - contesto ufficiale di come il Plugin Team usa Abilities API
• Pattern MCP + Abilities (mrtux.it) - pattern ufficiale Plugin Team per plugin AI
• AI-use disclosure Plugin Directory (mrtux.it) - compliance con il nuovo standard
• WP-CLI 2026 guida completa (mrtux.it) - automazione abilities via WP-CLI
• Rank Math SEO plugin - esempio di plugin che può esporre abilities SEO
• Wordfence Security plugin - esempio di plugin security che può esporre abilities scan
• Query Monitor plugin - tool di performance check utile come ability
• WordPress REST API authentication - per esporre abilities in sicurezza via REST
• Anthropic Model Context Protocol - contesto architetturale MCP che usa Abilities API