Index of every page on this site: llms.txt
All skills
automattic avatar

/wp-plugin-development

@48d4aa2 official
by automatticautomattic/agent-skills211 stars
37
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/automattic/agent-skills/wp-plugin-development

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈63 tokens for metadata: the name and description. ≈898 when used: this file. ≈996 more on demand in 6 files.

Description uses 3.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈251 characters, or 3.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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:

  • 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; use wp_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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning2mo5 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill provides guidance, references, and a non-malicious static analysis utility for WordPress plugin development. No security vulnerabilities or malicious behaviors were detected.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer9mo

    7/8 files flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 48d4aa2. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Dormantupdated 11 months ago
Other metadata
compatibility
Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI.
  • Security
  • wordpress
  • php
  • plugin-development
  • settings-api
  • hooks
  • wp-cli
  • activation-hooks
  • admin-ui
  • sanitization

README badge

README badge for automattic/agent-skills/wp-plugin-development

Develops WordPress plugins with guidance on architecture, hooks, lifecycle management, Settings API for admin UI, security patterns (nonces, capabilities, sanitization), and release packaging. Targets WordPress 6.9+ with PHP 7.2.24+, includes triage scripts and reference docs for common plugin tasks.

Generated from the current SKILL.md.

What WordPress and PHP versions does this skill target?
WordPress 6.9+ and PHP 7.2.24+. Target versions should be specified as input since they affect available APIs and placeholder support in $wpdb->prepare().
Does this skill work with multisite WordPress?
Yes. The skill supports both single-site and multisite setups; you should specify which when providing inputs.
What tools or commands does this skill require?
Filesystem-based workflow using bash and Node.js. Some workflows require WP-CLI for tasks like running migrations or cron jobs manually.
Does this skill handle plugin security (nonces, capabilities, sanitization)?
Yes. The skill covers the full security baseline: input validation/sanitization, output escaping, nonce and capability checks, and safe SQL with $wpdb->prepare().
Can this skill help with plugin activation, deactivation, and uninstall hooks?
Yes. The skill covers lifecycle management including activation/deactivation/uninstall behavior, migrations, schema versioning, and rewrite rule flushing.

Generated from the current SKILL.md. These answers refresh after source changes.