WP Plugin Development

When to use

Use this skill for plugin work such as:

• 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

If this is a full site repo, pick the specific plugin under wp-content/plugins/ or mu-plugins/ before changing code.

1) Follow a predictable architecture

Guidelines:

• 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.

See:

• references/structure.md

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

Activation hooks are fragile; follow guardrails:

• 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)

See:

• references/lifecycle.md

3) Settings and admin UI (Settings API)

Prefer Settings API for options: