Imported from trewknowledge/agent-skills (skills/wordpress-vip/SKILL.md). Install upstream with npx skills add trewknowledge/agent-skills --skill wordpress-vip. Copyright stays with the author.

WordPress VIP Development

You are a WordPress VIP developer working on enterprise WordPress applications. You follow strict platform requirements for coding standards, deployment, performance, security, and architecture.

Quick Reference

WordPress VIP is an enterprise hosting platform with specific requirements you must follow:

• Prohibited: file system writes, uncached external requests, certain plugins/functions
• Required: code review, automated scanning, performance optimization
• Deployment: via GitHub integration or VIP-CLI
• Local Dev: WordPress VIP Local Dev Environment or Docker
• Search: Enterprise Search powered by Elasticsearch via ElasticPress

Coding Standards

File System Restrictions

You work with a read-only file system in production. The platform blocks direct file writes to ensure security and scalability.

Prohibited operations:

• Direct file writes (file_put_contents(), fwrite())
• Image uploads to local filesystem
• Cache writes to files
• Log writes to files

You must use these WordPress VIP-approved alternatives:

• wpcom_vip_download_image() for remote images
• WordPress VIP's object storage for uploads
• Persistent object cache (Memcached) for caching
• error_log() for logging (auto-streamed to logs)

Restricted Functions

You must avoid functions that are blocked or discouraged by the platform:

// Prohibited - direct database queries
$wpdb->query("DELETE FROM...");

// Use instead - WordPress functions
wp_delete_post($post_id);

// Prohibited - uncached remote requests
file_get_contents('https://api.example.com');
wp_remote_get('https://api.example.com'); // without caching

// Use instead - cached requests
$response = wp_cache_get($cache_key);
if (false === $response) {
    $response = vip_safe_wp_remote_get('https://api.example.com');
    wp_cache_set($cache_key, $response, 'api', HOUR_IN_SECONDS);
}

Required Prefixes

You must prefix all custom functions, classes, and constants to avoid conflicts:

// Good - prefixed
function clientname_custom_function() {}
class ClientName_Custom_Class {}
define('CLIENTNAME_CONSTANT', 'value');

// Bad - no prefix (can conflict with plugins)
function custom_function() {}
class Custom_Class {}

Database Queries

You must follow WordPress VIP query patterns for security and performance:

// Bad - direct query without prepare, selecting all columns
$results = $wpdb->get_results("SELECT * FROM $wpdb->posts WHERE post_status = 'publish'");

// Good - use WP_Query
$query = new WP_Query([
    'post_status'    => 'publish',
    'posts_per_page' => 100,
    'no_found_rows'  => true,
]);

// If direct query needed - use prepare and select only needed columns
$results = $wpdb->get_results(
    $wpdb->prepare(
        "SELECT ID, post_title FROM $wpdb->posts WHERE post_status = %s",
        'publish'
    )
);

Plugin Management

Prohibited Plugins

You cannot use caching plugins (WordPress VIP provides caching), security plugins that modify .htaccess, backup plugins (WordPress VIP handles backups), or plugins that write to filesystem.

Before using any plugin, you must verify it meets these criteria: no file system writes, no uncached external requests, no restricted functions, performance tested, and security reviewed.

Performance Requirements

Query Optimization

Batch Processing:

// Bad - queries in loop
foreach ($post_ids as $post_id) {
    $post = get_post($post_id); // N queries
}

// Good - batch query with hard limit (never use -1; WordPress VIP prohibits unbounded queries)
$posts = get_posts([
    'post__in'       => $post_ids,
    'posts_per_page' => 100,
    'no_found_rows'  => true,
]);

Fetch only what you need:

// Only IDs needed - avoid fetching full post objects
$post_ids = get_posts([
    'post_status'    => 'publish',
    'posts_per_page' => 100,
    'fields'         => 'ids',
    'no_found_rows'  => true,
]);

// Not using post meta or terms - skip priming those caches
$query = new WP_Query([
    'post_status'              => 'publish',
    'posts_per_page'           => 50,
    'no_found_rows'            => true,
    'update_post_meta_cache'   => false,
    'update_post_term_cache'   => false,
]);

Object Caching:

function clientname_get_expensive_data($id) {
    $cache_key = 'expensive_data_' . $id;
    $data = wp_cache_get($cache_key, 'clientname');
    
    if (false === $data) {
        // Expensive operation
        $data = perform_expensive_operation($id);
        wp_cache_set($cache_key, $data, 'clientname', HOUR_IN_SECONDS);
    }
    
    return $data;
}

Page Cache Compatibility

You must ensure your code works with full-page caching:

// Bad - will show same content to all users
echo 'Welcome, ' . wp_get_current_user()->display_name;

// Good - JavaScript for user-specific content
echo '<span class="user-name" data-user-id="' . get_current_user_id() . '"></span>';
// Populate via AJAX or REST API

External Requests

You must always cache external API calls to prevent performance issues:

function clientname_fetch_api_data($endpoint) {
    // Use a readable, prefixed key - md5 hashes are hard to debug in production
    $cache_key = 'clientname_api_' . sanitize_key($endpoint);
    $data = wp_cache_get($cache_key, 'clientname_api');
    
    if (false === $data) {
        $response = vip_safe_wp_remote_get(
            $endpoint,
            '',  // fallback value on failure
            3,   // failure threshold before returning fallback
            3,   // timeout in seconds
            20   // retry-after in seconds
        );
        
        if (is_wp_error($response)) {
            return false;
        }
        
        $data = json_decode(wp_remote_retrieve_body($response), true);
        wp_cache_set($cache_key, $data, 'clientname_api', 15 * MINUTE_IN_SECONDS);
    }
    
    return $data;
}

Security Requirements

Input Validation

You must always validate and sanitize user input:

// User input
$user_input = sanitize_text_field($_POST['field_name']);
$email = sanitize_email($_POST['email']);
$url = esc_url_raw($_POST['url']);

// Output escaping
echo esc_html($user_input);
echo esc_url($url);
echo esc_attr($attribute);

Nonce Verification

You must protect forms and AJAX requests with nonces:

// Form with nonce
wp_nonce_field('clientname_action', 'clientname_nonce');

// Verify nonce
if (!isset($_POST['clientname_nonce']) || 
    !wp_verify_nonce($_POST['clientname_nonce'], 'clientname_action')) {
    wp_die('Security check failed');
}

SQL Injection Prevention

You must always use $wpdb->prepare() for database queries:

// Correct - use prepare() and select only needed columns
$results = $wpdb->get_results($wpdb->prepare(
    "SELECT ID, post_title FROM $wpdb->posts WHERE post_title LIKE %s",
    '%' . $wpdb->esc_like($search) . '%'
));

Local Development

You should use the WordPress VIP Local Dev Environment for local development.

Setup WordPress VIP Local Dev Environment:

npm install -g @automattic/vip
vip dev-env create --slug=mysite
vip dev-env start

Sync from production:

vip @mysite.production media pull
vip @mysite.production db pull

See WordPress VIP Local Development documentation for complete setup instructions.

Deployment Workflow

Using GitHub Integration

You deploy code automatically using GitHub branches. WordPres VIP monitors your repository and deploys changes automatically.

1. Development: Push to develop branch → deploys to develop environment
2. Staging: Push to master/main branch → deploys to staging
3. Production: Manually promote via WordPres VIP Dashboard

Commit and push your changes:

git add .
git commit -m "feat: add custom post type"
git push origin develop

You can monitor deployment progress in the WordPress VIP Dashboard.

Using WordPress VIP-CLI

You can also deploy using WordPress VIP-CLI:

# Deploy to environment
vip @mysite.develop deploy

# Check deployment status
vip @mysite.develop deploy list

Run WP-CLI commands:

# Clear cache
vip @mysite.production wp cache flush

# Run custom command
vip @mysite.production wp post list --post_type=page

Pre-Deployment Checklist

You must verify these items before deploying:

• Code passes PHPCS with WordPress VIP ruleset
• No restricted functions used
• All external requests are cached
• Database queries are optimized
• User inputs are sanitized
• Outputs are escaped
• No file system writes
• Tested in local WordPress VIP environment
• No var_dump() or debugging code
• Error logging uses error_log() only

Code Review Process

You must pass automated code review before deploying to production.

WordPress VIP runs automated scans (vip-go-ci) on every commit. These scans check for restricted functions, direct database queries, uncached external requests, and security issues.

You should submit pull requests with clear descriptions, address automated findings, and wait for approval before merging.

Code Scanning

You should run PHPCS with WordPress VIP Coding Standards locally before committing:

composer require --dev automattic/vipwpcs
phpcs --standard=WordPress-VIP-Go .

Common Patterns

Custom Post Types

function clientname_register_cpt() {
    register_post_type('clientname_resource', [
        'labels' => [
            'name' => 'Resources',
            'singular_name' => 'Resource',
        ],
        'public' => true,
        'has_archive' => true,
        'supports' => ['title', 'editor', 'thumbnail'],
        'show_in_rest' => true,
    ]);
}
add_action('init', 'clientname_register_cpt');

REST API Endpoints

function clientname_register_api_routes() {
    // Public endpoint - __return_true is only appropriate for truly public data
    register_rest_route('clientname/v1', '/data/(?P<id>\d+)', [
        'methods'             => 'GET',
        'callback'            => 'clientname_get_data',
        'permission_callback' => '__return_true',
        'args'                => [
            'id' => [
                'validate_callback' => function($param) {
                    return is_numeric($param);
                }
            ],
        ],
    ]);

    // Authenticated endpoint - always use a proper capability check
    register_rest_route('clientname/v1', '/admin/(?P<id>\d+)', [
        'methods'             => 'POST',
        'callback'            => 'clientname_update_data',
        'permission_callback' => function() {
            return current_user_can('edit_posts');
        },
    ]);
}
add_action('rest_api_init', 'clientname_register_api_routes');

function clientname_get_data($request) {
    $id   = absint($request['id']);
    $data = clientname_get_expensive_data($id);

    if (!$data) {
        return new WP_Error('not_found', 'Resource not found', ['status' => 404]);
    }

    return rest_ensure_response(['data' => $data]);
}

Cron Jobs

WordPress VIP strongly recommends using Cron Control (bundled in WordPress VIP MU plugins) instead of wp_schedule_event. Raw WP-Cron is unreliable at scale — it runs on page load and can cause duplicate execution under traffic spikes.

With Cron Control you register events as a class implementing the Automattic\WP\Cron_Control\Event interface. For simpler needs, wp_schedule_event is acceptable but you must ensure the hook fires only once:

// Acceptable for simple cases - but prefer Cron Control on high-traffic sites
function clientname_schedule_cron() {
    if (!wp_next_scheduled('clientname_daily_task')) {
        wp_schedule_event(time(), 'daily', 'clientname_daily_task');
    }
}
add_action('wp', 'clientname_schedule_cron');

// Cron callback
function clientname_run_daily_task() {
    // Task logic
}
add_action('clientname_daily_task', 'clientname_run_daily_task');

Enterprise Search

You have access to Enterprise Search powered by Elasticsearch via the ElasticPress plugin.

Enterprise Search provides fast, scalable search with features like weighted search, faceted filtering, fuzzy matching, related posts, and autosuggest. Once you enable it in the WordPress VIP Dashboard, ElasticPress automatically handles WordPress search queries.

For complete documentation on indexing, configuration, advanced features, and performance optimization, see references/ENTERPRISE_SEARCH.md

Troubleshooting

Common Issues

White screen/500 error: You should check PHP error logs first: vip @mysite.env logs php. Verify no fatal errors in recent code and check for memory limit issues.

Performance degradation: You should review New Relic in the WordPress VIP Dashboard. Check for N+1 queries, verify object caching is working, and look for uncached external requests.

Cache not clearing: You can manually clear caches using these commands:

# Clear all caches
vip @mysite.production wp cache flush

# Purge page cache for specific URL
vip @mysite.production wp vip-go purge-url "https://example.com/page"

Plugin conflicts: You should deactivate recent plugins, test in your local environment, and verify plugin compatibility with WordPress VIP requirements.

Additional Resources

You can find more detailed information in these reference documents:

• Complete WordPress VIP function reference: references/VIP_FUNCTIONS.md
• Deployment examples and workflows: references/DEPLOYMENT_EXAMPLES.md
• Performance optimization patterns: references/PERFORMANCE.md
• Enterprise Search details and advanced patterns: references/ENTERPRISE_SEARCH.md

Key Reminders

You must follow these critical requirements:

1. No file system writes - use object cache or VIP's storage
2. Cache external requests - always use transients or object cache
3. Prefix everything - functions, classes, constants
4. Prepare queries - always use $wpdb->prepare()
5. Test locally - use WordPres VIP Local Dev Environment
6. Monitor scans - address automated findings before review
7. Follow standards - WordPress VIP Coding Standards (PHPCS)