initial

.agents/skills/wp-plugin-development/references/data-and-cron.md

@@ -0,0 +1,19 @@
+# Data storage, cron, and upgrades
+
+Use this file when adding persistent storage, background jobs, or upgrade routines.
+
+## Data storage
+
+- Prefer Options API for small config/state.
+- Use custom tables only when needed; store schema version and provide upgrade paths.
+
+## Cron
+
+- Ensure tasks are idempotent (may run late or multiple times).
+- Provide a manual trigger path for debugging (WP-CLI or admin-only action).
+
+## Database safety note
+
+If using `$wpdb->prepare()`, avoid building queries with concatenated user input.
+Recent WordPress versions support identifier placeholders (`%i`) but you must not assume it exists without checking capabilities or target versions.
+

.agents/skills/wp-plugin-development/references/debugging.md

@@ -0,0 +1,19 @@
+# Debugging quick routes
+
+## Plugin doesn’t load / fatal errors
+
+- Confirm correct plugin main file and header.
+- Check PHP error logs and `WP_DEBUG_LOG`.
+- If the repo is a site repo, confirm you edited the correct plugin under `wp-content/plugins/`.
+
+## Activation hook surprises
+
+- Hooks must be registered at top-level.
+- Activation runs in a special context; avoid assuming other hooks already ran.
+
+## Settings not saving
+
+- Confirm `register_setting()` is called.
+- Confirm the option group matches the form.
+- Confirm capability checks and nonces.
+

.agents/skills/wp-plugin-development/references/lifecycle.md

@@ -0,0 +1,33 @@
+# Activation, deactivation, uninstall
+
+Use this file for lifecycle changes and data cleanup.
+
+## Activation / deactivation hooks
+
+- `register_activation_hook( __FILE__, 'callback' )`
+- `register_deactivation_hook( __FILE__, 'callback' )`
+
+Guardrails:
+
+- These hooks must be registered at top-level (not inside other hooks).
+- If you flush rewrite rules, ensure rules are registered first (often via a shared function called both on `init` and activation).
+
+Upstream reference:
+
+- https://developer.wordpress.org/plugins/plugin-basics/activation-deactivation-hooks/
+
+## Uninstall
+
+Preferred approaches:
+
+- `uninstall.php` (runs only on uninstall)
+- `register_uninstall_hook()`
+
+Guardrails:
+
+- Check `WP_UNINSTALL_PLUGIN` before running destructive cleanup.
+
+Upstream reference:
+
+- https://developer.wordpress.org/plugins/plugin-basics/uninstall-methods/
+

.agents/skills/wp-plugin-development/references/security.md

@@ -0,0 +1,29 @@
+# Security guardrails (plugin work)
+
+Use this file when making security fixes or when handling any input/output.
+
+## Nonces + permissions
+
+- Nonces help prevent CSRF, not authorization.
+- Always pair nonces with capability checks (`current_user_can()` or a more specific capability).
+
+Upstream reference:
+
+- https://developer.wordpress.org/apis/security/nonces/
+
+## Sanitization and escaping
+
+Golden rule:
+
+- sanitize/validate on input, escape on output.
+
+Practical rules:
+
+- never process the entire `$_POST` / `$_GET` array; read explicit keys
+- use `wp_unslash()` before sanitizing when needed
+- use prepared statements for SQL; avoid interpolating user input into queries
+
+Common review guidance:
+
+- https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/
+

.agents/skills/wp-plugin-development/references/settings-api.md

@@ -0,0 +1,22 @@
+# Settings API (admin options)
+
+Use this file when adding settings pages or storing user-configurable options.
+
+Core APIs:
+
+- `register_setting()`
+- `add_settings_section()`
+- `add_settings_field()`
+
+Upstream references:
+
+- Settings API overview: https://developer.wordpress.org/plugins/settings/settings-api/
+- Register settings: https://developer.wordpress.org/plugins/settings/registration/
+- Add settings fields: https://developer.wordpress.org/plugins/settings/settings-fields/
+
+Practical guardrails:
+
+- Use `sanitize_callback` to validate/sanitize data.
+- Use capability checks (commonly `manage_options`) for settings screens and saves.
+- Escape values on output (`esc_attr`, `esc_html`, etc.).
+

.agents/skills/wp-plugin-development/references/structure.md

@@ -0,0 +1,16 @@
+# Plugin structure and loading
+
+Use this file when introducing or refactoring a plugin architecture.
+
+## Core concepts
+
+- Main plugin file contains the plugin header and bootstraps the plugin.
+- Prefer predictable init:
+  - minimal boot file
+  - a loader/class that registers hooks
+  - admin-only code behind admin hooks
+
+Upstream reference:
+
+- https://developer.wordpress.org/plugins/plugin-basics/
+