WordPress Development Best Practices Skill

WordPress Development Best Practices

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

What This Skill Provides

Coding Standards - PHP, JS, CSS conventions following WordPress standards
Custom Post Types - Complete CPT registration and management guide
Security - Sanitization, escaping, nonces, capability checks
Performance - Caching, query optimization, asset loading
Hooks & Filters - Actions and filters reference with examples
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

Agent Skills: WordPress Development Best Practices

Install this agent skill to your local

Skill Files