Wp Plugin Development

1---
2name: wp-plugin-development
3description: "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."
4compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
5---
6 
7# WP Plugin Development
8 
9## When to use
10 
11Use this skill for plugin work such as:
12 
13- creating or refactoring plugin structure (bootstrap, includes, namespaces/classes)
14- adding hooks/actions/filters
15- activation/deactivation/uninstall behavior and migrations
16- adding settings pages / options / admin UI (Settings API)
17- security fixes (nonces, capabilities, sanitization/escaping, SQL safety)
18- packaging a release (build artifacts, readme, assets)
19 
20## Inputs required
21 
22- Repo root + target plugin(s) (path to plugin main file if known).
23- Where this plugin runs: single site vs multisite; WP.com conventions if applicable.
24- Target WordPress + PHP versions (affects available APIs and placeholder support in `$wpdb->prepare()`).
25 
26## Procedure
27 
28### 0) Triage and locate plugin entrypoints
29 
301. Run triage:
31   - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
322. Detect plugin headers (deterministic scan):
33   - `node skills/wp-plugin-development/scripts/detect_plugins.mjs`
34 
35If this is a full site repo, pick the specific plugin under `wp-content/plugins/` or `mu-plugins/` before changing code.
36 
37### 1) Follow a predictable architecture
38 
39Guidelines:
40 
41- Keep a single bootstrap (main plugin file with header).
42- Avoid heavy side effects at file load time; load on hooks.
43- Prefer a dedicated loader/class to register hooks.
44- Keep admin-only code behind `is_admin()` (or admin hooks) to reduce frontend overhead.
45 
46See:
47- `references/structure.md`
48 
49### 2) Hooks and lifecycle (activation/deactivation/uninstall)
50 
51Activation hooks are fragile; follow guardrails:
52 
53- register activation/deactivation hooks at top-level, not inside other hooks
54- flush rewrite rules only when needed and only after registering CPTs/rules
55- uninstall should be explicit and safe (`uninstall.php` or `register_uninstall_hook`)
56 
57See:
58- `references/lifecycle.md`
59 
60### 3) Settings and admin UI (Settings API)
61 
62Prefer Settings API for options:
63 
64- `register_setting()`, `add_settings_section()`, `add_settings_field()`
65- sanitize via `sanitize_callback`
66 
67See:
68- `references/settings-api.md`
69 
70### 4) Security baseline (always)
71 
72Before shipping:
73 
74- Validate/sanitize input early; escape output late.
75- Use nonces to prevent CSRF *and* capability checks for authorization.
76- Avoid directly trusting `$_POST` / `$_GET`; use `wp_unslash()` and specific keys.
77- Use `$wpdb->prepare()` for SQL; avoid building SQL with string concatenation.
78 
79See:
80- `references/security.md`
81 
82### 5) Data storage, cron, migrations (if needed)
83 
84- Prefer options for small config; custom tables only if necessary.
85- For cron tasks, ensure idempotency and provide manual run paths (WP-CLI or admin).
86- For schema changes, write upgrade routines and store schema version.
87 
88See:
89- `references/data-and-cron.md`
90 
91## Verification
92 
93- Plugin activates with no fatals/notices.
94- Settings save and read correctly (capability + nonce enforced).
95- Uninstall removes intended data (and nothing else).
96- Run repo lint/tests (PHPUnit/PHPCS if present) and any JS build steps if the plugin ships assets.
97 
98## Failure modes / debugging
99 
100- Activation hook not firing:
101  - hook registered incorrectly (not in main file scope), wrong main file path, or plugin is network-activated
102- Settings not saving:
103  - settings not registered, wrong option group, missing capability, nonce failure
104- Security regressions:
105  - nonce present but missing capability checks; or sanitized input not escaped on output
106 
107See:
108- `references/debugging.md`
109 
110## Escalation
111 
112For canonical detail, consult the Plugin Handbook and security guidelines before inventing patterns.
113