Add wp-plugin-check skill (Plugin Check / PCP) + small wp-plugin-development guidance

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 <slug>",
+    "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"
+  ]
+}

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 <plugin-slug-or-file>`
+
+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 <slug> --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

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 <plugin-slug-or-file>`
+
+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