WordPress Development Best Practices

Comprehensive development guidance for WordPress themes and plugins following 2025 standards.

What This Skill Provides

1. Coding Standards - PHP, JS, CSS conventions following WordPress standards
2. Custom Post Types - Complete CPT registration and management guide
3. Security - Sanitization, escaping, nonces, capability checks
4. Performance - Caching, query optimization, asset loading
5. Hooks & Filters - Actions and filters reference with examples
6. Template Hierarchy - Theme template structure and overrides

Quick Reference

Do's

• Use WordPress APIs (don't reinvent the wheel)
• Sanitize all input (sanitize_* functions)
• Escape all output (esc_* functions)
• Use prepared statements for SQL ($wpdb->prepare)
• Enqueue scripts/styles properly (wp_enqueue_*)
• Use transients for expensive operations
• Follow the template hierarchy
• Use hooks instead of modifying core
• Prefix all functions, classes, and global variables
• Use WP-CLI for automation tasks

Don'ts

• Modify WordPress core files (NEVER)
• Use query_posts() - use WP_Query instead
• Echo untrusted data without escaping
• Store sensitive data in plain text options
• Use extract() on untrusted data
• Suppress errors with @ operator
• Use deprecated functions
• Hard-code URLs or file paths
• Skip nonce verification on forms
• Use mysql_* functions - use $wpdb

Documentation

Detailed documentation available in /docs/:

File	Contents
coding-standards.md	PHP, JS, CSS naming and formatting
custom-post-types.md	CPT registration, labels, capabilities
security.md	Input/output handling, nonces, SQL safety
performance.md	Caching, optimization, lazy loading
hooks-filters.md	Common actions/filters with examples
template-hierarchy.md	Template files and overrides

Code Templates

Ready-to-use templates in /templates/:

Template	Purpose
custom-post-type.php	CPT registration boilerplate
taxonomy.php	Custom taxonomy registration
meta-box.php	Admin meta box with save handling
rest-api-endpoint.php	Custom REST API endpoint
plugin-skeleton/	Complete plugin starter files

Usage Examples

Create a Custom Post Type

Ask Claude:

• "Create a 'Property' custom post type for real estate"
• "Add a custom post type for team members with a photo field"
• "Register a 'Portfolio' CPT with custom taxonomies"

Security Review

Ask Claude:

• "Review this form handler for security issues"
• "Check if this plugin follows WordPress security best practices"
• "Add proper sanitization and escaping to this code"

Performance Optimization

Ask Claude:

• "Optimize this WP_Query for better performance"
• "Add caching to this expensive database operation"
• "Review asset loading for this theme"

Code Generation

Use the scaffold script to generate boilerplate:

# Generate a custom post type
python3 /root/.claude/skills/wordpress-dev/scripts/scaffold.py \
  --type cpt \
  --name "Property" \
  --slug "property" \
  --output /path/to/theme/inc/

# Generate a custom taxonomy
python3 /root/.claude/skills/wordpress-dev/scripts/scaffold.py \
  --type taxonomy \
  --name "Property Type" \
  --slug "property-type" \
  --post-type "property" \
  --output /path/to/theme/inc/

WordPress 6.x / Block Theme Notes

Full Site Editing (FSE)

For block themes (WordPress 6.0+):

theme/
├── theme.json          # Global styles and settings
├── templates/          # Block templates (HTML)
│   ├── index.html
│   ├── single.html
│   └── page.html
├── parts/              # Block template parts
│   ├── header.html
│   └── footer.html
└── patterns/           # Block patterns
    └── hero.php

theme.json Best Practices

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {"slug": "primary", "color": "#1a1a1a", "name": "Primary"}
      ]
    },
    "typography": {
      "fontFamilies": [
        {"fontFamily": "Inter, sans-serif", "slug": "body", "name": "Body"}
      ]
    },
    "spacing": {
      "units": ["px", "rem", "%"]
    }
  }
}

Common Patterns

Safe Database Query

global $wpdb;
$results = $wpdb->get_results(
    $wpdb->prepare(
        "SELECT * FROM {$wpdb->posts} WHERE post_type = %s AND post_status = %s",
        'property',
        'publish'
    )
);

AJAX Handler

// Register AJAX action
add_action('wp_ajax_my_action', 'my_ajax_handler');
add_action('wp_ajax_nopriv_my_action', 'my_ajax_handler');

function my_ajax_handler() {
    // Verify nonce
    check_ajax_referer('my_nonce', 'security');

    // Check capability
    if (!current_user_can('edit_posts')) {
        wp_send_json_error('Unauthorized', 403);
    }

    // Sanitize input
    $data = sanitize_text_field($_POST['data']);

    // Process and respond
    wp_send_json_success(['message' => 'Done']);
}

Enqueue Scripts Properly

function theme_enqueue_assets() {
    // CSS
    wp_enqueue_style(
        'theme-style',
        get_stylesheet_uri(),
        [],
        filemtime(get_stylesheet_directory() . '/style.css')
    );

    // JS with dependencies
    wp_enqueue_script(
        'theme-main',
        get_theme_file_uri('/assets/js/main.js'),
        ['jquery'],
        filemtime(get_theme_file_path('/assets/js/main.js')),
        true // In footer
    );

    // Localize for AJAX
    wp_localize_script('theme-main', 'themeData', [
        'ajaxUrl' => admin_url('admin-ajax.php'),
        'nonce'   => wp_create_nonce('theme_nonce'),
    ]);
}
add_action('wp_enqueue_scripts', 'theme_enqueue_assets');

Related Skills

• wordpress-admin: Page/post management, WP-CLI, REST API
• seo-optimizer: Yoast/Rank Math audit and optimization
• visual-qa: Screenshot testing with animation handling
• brand-guide: Brand documentation generation

Resources

• WordPress Coding Standards
• Theme Developer Handbook
• Plugin Developer Handbook
• Block Editor Handbook
• REST API Handbook