WP Plugin Development

When to use

• creating or refactoring plugin structure (bootstrap, includes, namespaces/classes)
• adding hooks/actions/filters
• activation/deactivation/uninstall behavior and migrations
• adding settings pages / options / admin UI (Settings API)
• security fixes (nonces, capabilities, sanitization/escaping, SQL safety)
• packaging a release (build artifacts, readme, assets)

Inputs required

• Repo root + target plugin(s) (path to plugin main file if known).
• Where this plugin runs: single site vs multisite; WP.com conventions if applicable.
• Target WordPress + PHP versions (affects available APIs and placeholder support in

  $wpdb->prepare()

  ).

Procedure

0) Triage and locate plugin entrypoints

1. Run triage:

   • node skills/wp-project-triage/scripts/detect_wp_project.mjs

2. Detect plugin headers (deterministic scan):

   • node skills/wp-plugin-development/scripts/detect_plugins.mjs

wp-content/plugins/

mu-plugins/

1) Follow a predictable architecture

• Keep a single bootstrap (main plugin file with header).
• Avoid heavy side effects at file load time; load on hooks.
• Prefer a dedicated loader/class to register hooks.
• Keep admin-only code behind

  is_admin()

  (or admin hooks) to reduce frontend overhead.

• references/structure.md

2) Hooks and lifecycle (activation/deactivation/uninstall)

• register activation/deactivation hooks at top-level, not inside other hooks
• flush rewrite rules only when needed and only after registering CPTs/rules
• uninstall should be explicit and safe (

  uninstall.php

  or

  register_uninstall_hook

  )

• references/lifecycle.md

3) Settings and admin UI (Settings API)

• register_setting()

  ,

  add_settings_section()

  ,

  add_settings_field()

• sanitize via

  sanitize_callback

• references/settings-api.md

4) Security baseline (always)

• Validate/sanitize input early; escape output late.
• Use nonces to prevent CSRF and capability checks for authorization.
• Avoid directly trusting

  $_POST

  /

  $_GET

  ; use

  wp_unslash()

  and specific keys.
• Use

  $wpdb->prepare()

  for SQL; avoid building SQL with string concatenation.

• references/security.md

5) Data storage, cron, migrations (if needed)

• Prefer options for small config; custom tables only if necessary.
• For cron tasks, ensure idempotency and provide manual run paths (WP-CLI or admin).
• For schema changes, write upgrade routines and store schema version.

• references/data-and-cron.md

Verification

• Plugin activates with no fatals/notices.
• Settings save and read correctly (capability + nonce enforced).
• Uninstall removes intended data (and nothing else).
• Run repo lint/tests (PHPUnit/PHPCS if present) and any JS build steps if the plugin ships assets.

Failure modes / debugging

• Activation hook not firing:
  • hook registered incorrectly (not in main file scope), wrong main file path, or plugin is network-activated
• Settings not saving:
  • settings not registered, wrong option group, missing capability, nonce failure
• Security regressions:
  • nonce present but missing capability checks; or sanitized input not escaped on output

• references/debugging.md

Escalation