wp-plugin-development
Use when developing WordPress plugins: architecture and hooks, activation/deactivation/uninstall, admin UI and Settings API, data storage, cron/tasks, security (nonces/capabilities/sanitization/escaping), and release packaging.
When & Why to Use This Skill
This Claude skill is a comprehensive toolkit for professional WordPress plugin development, designed to streamline the creation of secure, scalable, and high-performance extensions. It provides expert guidance on modern PHP architecture, WordPress hooks, and the Settings API, ensuring all code adheres to official WordPress Handbook standards and security best practices for versions 6.9 and above.
Use Cases
- Scaffolding new WordPress plugins with a clean, class-based architecture, namespaces, and proper directory structures.
- Implementing secure admin interfaces and settings pages using the WordPress Settings API with built-in sanitization and validation.
- Hardening plugin security by automatically incorporating nonces, capability checks, and prepared SQL statements to prevent CSRF and injection attacks.
- Managing complex plugin lifecycles, including activation routines, deactivation hooks, and explicit uninstallation scripts for database cleanup.
- Configuring background processing and scheduled tasks via WP-Cron with support for WP-CLI manual execution paths.
- Preparing production-ready release packages, including build artifacts, readme files, and asset optimization.
| name | wp-plugin-development |
|---|---|
| description | "Use when developing WordPress plugins: architecture and hooks, activation/deactivation/uninstall, admin UI and Settings API, data storage, cron/tasks, security (nonces/capabilities/sanitization/escaping), and release packaging." |
| compatibility | "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI." |
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
- Run triage:
node skills/wp-project-triage/scripts/detect_wp_project.mjs
- 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.phporregister_uninstall_hook)
See:
references/lifecycle.md
3) Settings and admin UI (Settings API)
Prefer Settings API for options:
register_setting(),add_settings_section(),add_settings_field()- sanitize via
sanitize_callback
See:
references/settings-api.md
4) Security baseline (always)
Before shipping:
- Validate/sanitize input early; escape output late.
- Use nonces to prevent CSRF and capability checks for authorization.
- Avoid directly trusting
$_POST/$_GET; usewp_unslash()and specific keys. - Use
$wpdb->prepare()for SQL; avoid building SQL with string concatenation.
See:
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.
See:
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
See:
references/debugging.md
Escalation
For canonical detail, consult the Plugin Handbook and security guidelines before inventing patterns.