From d327e1cef5ebffb654c2368141b851c5efaffdd1 Mon Sep 17 00:00:00 2001 From: Andrius Date: Thu, 4 Jun 2026 13:17:59 +0200 Subject: [PATCH] wp-plugin-check: add new skill and link it from wp-plugin-development Adds a tightly-scoped wp-plugin-check skill that runs and interprets the official Plugin Check (PCP) tool (wp plugin check) against current WordPress.org standards: static vs runtime checks, filtering by category (security, performance, accessibility, i18n), reading errors vs warnings, and gating releases/CI. Routes fixes to the existing domain skills. Also adds small, factual guidance to wp-plugin-development: - a Dependencies & headers step (Requires Plugins header, WP 6.5+) - a pre-release Plugin Check step + verification bullets pointing to the new skill Includes the required eval scenario for the new skill. Co-authored-by: Cursor --- eval/scenarios/plugin-check-run-and-fix.json | 21 ++++ skills/wp-plugin-check/SKILL.md | 106 +++++++++++++++++++ skills/wp-plugin-development/SKILL.md | 18 ++++ 3 files changed, 145 insertions(+) create mode 100644 eval/scenarios/plugin-check-run-and-fix.json create mode 100644 skills/wp-plugin-check/SKILL.md diff --git a/eval/scenarios/plugin-check-run-and-fix.json b/eval/scenarios/plugin-check-run-and-fix.json new file mode 100644 index 0000000..dc53f45 --- /dev/null +++ b/eval/scenarios/plugin-check-run-and-fix.json @@ -0,0 +1,21 @@ +{ + "name": "Run Plugin Check and fix findings", + "skills": ["wordpress-router", "wp-project-triage", "wp-plugin-check", "wp-plugin-development"], + "query": "Run Plugin Check on this plugin before I submit it to WordPress.org and fix the security and i18n problems it reports.", + "expected_behavior": [ + "Step 1: Run wordpress-router / wp-project-triage to classify the repo and locate the plugin", + "Step 2: Route to wp-plugin-check", + "Step 3: Run detect_plugin_check.mjs to confirm WP-CLI and the plugin-check plugin, and get the suggested command", + "Step 4: Run static checks first with wp plugin check ", + "Step 5: Triage by category, focusing on security and internationalization", + "Step 6: Treat errors as blocking; route fixes (escaping/nonces/capabilities) to wp-plugin-development security guidance", + "Step 7: Fix the underlying code rather than excluding files or suppressing findings", + "Step 8: Re-run the same wp plugin check command and confirm no errors remain in the required categories" + ], + "success_criteria": [ + "Plugin Check is actually run via wp plugin check (not guessed)", + "Security and i18n findings are fixed in code", + "No findings are suppressed or excluded to force a pass", + "Command is re-run after fixes and reports clean required categories" + ] +} diff --git a/skills/wp-plugin-check/SKILL.md b/skills/wp-plugin-check/SKILL.md new file mode 100644 index 0000000..afd596d --- /dev/null +++ b/skills/wp-plugin-check/SKILL.md @@ -0,0 +1,106 @@ +--- +name: wp-plugin-check +description: "Use when running or interpreting Plugin Check (PCP) for a WordPress plugin: pre-submission and pre-release quality gates, the wp plugin check CLI, static vs runtime checks, filtering by category (security, performance, accessibility, internationalization), reading errors vs warnings, and wiring Plugin Check into CI." +compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Requires the Plugin Check plugin and (preferably) WP-CLI." +--- + +# WP Plugin Check (PCP) + +## When to use + +Use this skill when the goal is to verify a plugin against current WordPress.org +standards and development best practices, for example: + +- preparing a plugin for submission or a release and you want it to pass review +- you were asked to run "Plugin Check" / "PCP" or to check security, performance, accessibility, or i18n compliance +- a plugin was rejected or flagged and you need to reproduce and fix the findings +- adding an automated quality gate to CI + +For building plugin features, use `wp-plugin-development`. For the human-readable +directory rules (GPL, naming/trademark), use `wp-plugin-directory-guidelines`. + +## Inputs required + +- The target plugin: slug, path, or zip (and the repo root if running locally). +- Environment + safety: dev/staging/prod, and whether you may install the Plugin Check plugin / run WP-CLI. +- Whether runtime checks are wanted (they execute plugin code and need extra setup). + +## Procedure + +### 0) Confirm the tooling + +- Confirm WP-CLI is available (`wp --info`). +- Confirm the `plugin-check` plugin is installed/active; if missing and allowed, install it: `wp plugin install plugin-check --activate`. +- Identify the target plugin's slug (its folder name under `wp-content/plugins/`) or path. + +### 1) Run static checks first + +Static checks are the default and require no plugin execution: + +- `wp plugin check ` + +You can also point at an arbitrary path or zip/URL: + +- `wp plugin check /path/to/plugin` +- `wp plugin check https://example.com/plugin.zip` + +### 2) Add runtime checks only if needed + +Runtime checks execute plugin code and must load the checker before WordPress: + +- `wp plugin check --require=./wp-content/plugins/plugin-check/cli.php` + +### 3) Filter by category to focus the work + +Run one category at a time when triaging a large result set. Categories include +security, performance, accessibility, and internationalization, plus general/plugin- +repository checks (readme and header requirements). Category names and the output +format flag can change between releases, so confirm the exact flags with +`wp plugin check --help` in the installed version. + +### 4) Interpret results: errors vs warnings + +- Treat **errors** as blocking; they typically map to review-blocking guideline issues. +- Triage **warnings** by category and risk (security and performance first). +- Route each finding to the skill that fixes it: security/escaping/nonces and i18n -> `wp-plugin-development`; query/asset performance -> `wp-performance`; type issues surfaced while fixing -> `wp-phpstan`; readme/header/naming/GPL -> `wp-plugin-directory-guidelines`. + +### 5) Re-run until the required categories are clean + +Re-run the same command after each fix. Do not suppress findings to pass; fix the +underlying code. + +### 6) Gate releases / CI (optional) + +Run Plugin Check non-interactively in a real WordPress + WP-CLI environment (with the +`plugin-check` plugin active), emit machine-readable output, and fail the job on a +non-zero exit / when errors are present. Confirm the `--format` flag with +`wp plugin check --help`, and prefer the repo's existing CI tooling (e.g. `wp-env`, +the WordPress Plugin Check GitHub Action). + +## Verification + +- The same `wp plugin check` command was re-run after fixes and reports no errors in the required categories. +- Findings were fixed in code, not ignored or excluded. +- If runtime checks were used, they ran against a representative environment. +- CI (if configured) fails on Plugin Check errors. + +## Failure modes / debugging + +- "Command not found: wp plugin check": + - the `plugin-check` plugin is not installed/active, or WP-CLI is not on PATH — re-check Step 0. +- Runtime checks report nothing or error out: + - the `--require=.../plugin-check/cli.php` path is wrong, or the plugin needs activation/data to exercise the code path. +- Huge result set: + - run one category at a time (Step 3) and fix errors before warnings. +- "Passes locally, fails review": + - reviewers may run additional/runtime checks and a newer Plugin Check version; update the plugin and re-run. + +## Escalation + +- Plugin Check is a non-perfect aid, not a guarantee of approval. For ambiguous guideline questions, consult `wp-plugin-directory-guidelines` and the WordPress.org review guidelines. +- If a finding requires a dependency or API you cannot confirm, ask for the version/source before changing types or behavior. + +Upstream references: + +- https://wordpress.org/plugins/plugin-check/ +- https://github.com/WordPress/plugin-check diff --git a/skills/wp-plugin-development/SKILL.md b/skills/wp-plugin-development/SKILL.md index 4456de5..ed2bfb5 100644 --- a/skills/wp-plugin-development/SKILL.md +++ b/skills/wp-plugin-development/SKILL.md @@ -88,11 +88,29 @@ See: See: - `references/data-and-cron.md` +### 6) Dependencies and headers + +- If the plugin depends on other WordPress.org plugins, declare them with the `Requires Plugins` header (WordPress 6.5+, a comma-separated list of WordPress.org slugs) instead of bundling or silently failing. Still guard calls with `class_exists()` / `function_exists()` so the plugin degrades gracefully. +- Keep `Requires at least`, `Requires PHP`, `Text Domain`, and (when self-updating) `Update URI` headers accurate; they gate install/activation and update behavior. + +Upstream reference: +- https://developer.wordpress.org/plugins/plugin-basics/header-requirements/ + +### 7) Pre-release quality checks + +Before packaging or submitting, run Plugin Check (PCP) to catch security, performance, accessibility, and i18n issues against current WordPress.org standards: + +- `wp plugin check ` + +For the full workflow (categories, runtime checks, interpreting results, CI gating), use the `wp-plugin-check` skill. + ## Verification - Plugin activates with no fatals/notices. - Settings save and read correctly (capability + nonce enforced). - Uninstall removes intended data (and nothing else). +- `Requires Plugins` is declared when the plugin depends on other WordPress.org plugins (and the plugin still degrades gracefully if a dependency is missing). +- Plugin Check reports no errors in required categories (`wp plugin check`); see the `wp-plugin-check` skill. - Run repo lint/tests (PHPUnit/PHPCS if present) and any JS build steps if the plugin ships assets. ## Failure modes / debugging