AI Filters

This page documents filters for customizing the AI assistant — prompts, models, and request parameters.

Filter	Description
unblock/ai/prompts	System prompt parts before assembly
unblock/ai/agents	AI agents configuration
unblock/ai/skills	AI skills configuration
unblock/ai/timeout	AI request timeout
unblock/ai/max_tokens	Maximum tokens for responses
unblock/ai/model_preference	AI model override

ai/prompts

Filter AI system prompt parts before assembly.

apply_filters( 'unblock/ai/prompts', array $parts, string $agent );

Parameter	Type	Description
$parts	string[]	Array of prompt instruction strings
$agent	string	Agent identifier ('builder', 'designer', 'content')

Example: Add Custom Instruction

add_filter( 'unblock/ai/prompts', function( $parts, $agent ) {

    $parts[] = 'Use {{ product.price|currency }} for product prices.';

    return $parts;

}, 10, 2 );

Example: Agent-Specific Prompt

add_filter( 'unblock/ai/prompts', function( $parts, $agent ) {

    if ( 'content' === $agent ) {
        $parts[] = 'Always write in British English.';
    }

    return $parts;

}, 10, 2 );

ai/agents

Filter AI agents configuration.

apply_filters( 'unblock/ai/agents', array $agents );

Parameter	Type	Description
$agents	array	Registered agents configuration

Each agent is keyed by its identifier and supports: label, description, icon, role (prompt key for system role), prompts (prompt part keys), tools (tool names).

Built-in agents: builder, designer, content (writer).

Example: Restrict Designer Tools

add_filter( 'unblock/ai/agents', function( $agents ) {

    // Only allow style changes, no attribute updates.
    $agents['designer']['tools'] = [ 'create_styles' ];

    return $agents;

} );

ai/skills

Filter AI skills (slash commands) configuration.

apply_filters( 'unblock/ai/skills', array $skills );

Parameter	Type	Description
$skills	array	Registered skills configuration

Each skill is keyed by its slug and supports: label, description, icon, prompts (prompt part keys), tools (tool names), capability (required capability), server_tool (bool).

Example: Register Custom Skill

add_filter( 'unblock/ai/skills', function( $skills ) {

    $skills['seo-audit'] = [
        'label'       => __( 'SEO audit', 'flavor' ),
        'description' => __( 'Check headings, alt text, and meta tags', 'flavor' ),
        'icon'        => 'search',
        'prompts'     => [ 'skill-seo' ],
        'tools'       => [],
    ];

    return $skills;

} );

Example: Remove a Built-in Skill

add_filter( 'unblock/ai/skills', function( $skills ) {

    unset( $skills['generate-images'] );

    return $skills;

} );

ai/timeout

Filter the AI request timeout.

apply_filters( 'unblock/ai/timeout', int $timeout );

Parameter	Type	Description
$timeout	int	Timeout in seconds. Default: 600

Example: Reduce Timeout

add_filter( 'unblock/ai/timeout', fn( $timeout ) => 120 );

ai/max_tokens

Filter the maximum tokens for AI responses.

apply_filters( 'unblock/ai/max_tokens', int $max_tokens );

Parameter	Type	Description
$max_tokens	int	Maximum token count

Example: Limit Response Length

add_filter( 'unblock/ai/max_tokens', fn( $max_tokens ) => 2048 );

ai/model_preference

Filter the AI model preference. Return a model identifier to override the default.

apply_filters( 'unblock/ai/model_preference', string $model );

Parameter	Type	Description
$model	string	Model identifier

Example: Use a Specific Model

add_filter( 'unblock/ai/model_preference', fn( $model ) => 'claude-sonnet-4-20250514' );

Next steps

• Data filters — register custom providers and functions
• Actions — plugin lifecycle hooks