# Wp Plugin Development

Use when developing WordPress plugins: architecture and hooks...

- Repository: https://github.com/WordPress/agent-skills (2319 stars)
- Category: Design
- License: see repository
- Last updated: 2026-10-26
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add WordPress/agent-skills --skill wp-plugin-development -g -a claude-code -y`
Codex: `npx skills add WordPress/agent-skills --skill wp-plugin-development -g -a codex -y`
Cursor: `npx skills add WordPress/agent-skills --skill wp-plugin-development -g -a cursor -y`
Gemini CLI: `npx skills add WordPress/agent-skills --skill wp-plugin-development -g -a gemini-cli -y`

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:

The rest: https://github.com/WordPress/agent-skills/blob/HEAD/skills/wp-plugin-development/SKILL.md