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

/wp-plugin-directory-guidelines

@7374e6f official
by wordpresswordpress/agent-skills2.4k stars
351
Run it yourself

Use when reviewing WordPress plugins for GPL compliance, checking license headers or compatibility, evaluating upsell/freemium/trialware patterns, validating plugin naming or trademark rules, checking plugin slugs, running Plugin Check (PCP) to validate plugin changes, interpreting its findings, understanding why a plugin was rejected from WordPress.org, or answering questions about the 18 WordPress.org Plugin Directory guidelines.

Use this Skill: https://skilld.dev/gh/wordpress/agent-skills/wp-plugin-directory-guidelines

Nothing lands on disk. Nothing to clean up.

Fork this Skill

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

referencesplugin-check.md

≈1.8k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Plugin Check validation

Use Plugin Check (PCP) as a validation layer for plugin code reviews and completed changes. It complements the directory checklist, functional tests, and human review; it does not certify approval or correctness.

1. Identify the plugin and environment

  • Inspect the plugin entrypoint, declared WordPress/PHP versions, project instructions, and available lint/build/test commands before reviewing or changing code.
  • Identify the actual plugin slug or source path and a local WordPress installation containing the code being reviewed. Reuse the project's command runner (for example, its existing container wrapper) and configuration.
  • Use a local development/test site, not production. Plugin Check runtime checks execute plugin code.
  • Verify WP-CLI and WordPress are available, then inspect wp help plugin check to confirm supported options. Plugin Check supplies this command; it is not built into WP-CLI alone.

From the local WordPress root, these commands inspect prerequisites:

wp --info
wp core is-installed
wp plugin is-installed plugin-check
wp plugin is-active plugin-check
wp help plugin check

If local environment setup is within the task's authorization, install and activate PCP when missing:

wp plugin install plugin-check --activate

If already installed but inactive, use wp plugin activate plugin-check. Preserve an existing installation rather than reinstalling it. When running outside the WordPress root, add --path=/actual/wordpress/root or use the project's configured runner for every site command.

If tooling is unavailable, continue the source review and give concrete commands adapted to the known environment. Mark automated validation as not run, with the missing prerequisite. An unavailable check is not a pass.

Even when setup is excluded, include the complete follow-up sequence as instructions only: obtain WP-CLI and a local WordPress test site, make the target source available there, install/activate PCP if needed, inspect command help, then run the checks. Do not start at wp plugin check when its prerequisites are missing. For a future site with WP-CLI ready and PCP absent:

wp --path=/actual/wordpress/root core is-installed
wp --path=/actual/wordpress/root plugin install plugin-check --activate
wp --path=/actual/wordpress/root help plugin check
wp --path=/actual/wordpress/root plugin check /actual/path/to/plugin

Replace placeholders with known paths and the target plugin; label unknown paths explicitly. For an existing PCP installation use the inspection/activation steps above instead of reinstalling. Include the runtime loader below when runtime coverage is requested.

2. Run tests and checks

Run the relevant existing lint/tests and required asset builds. Then run Plugin Check against the actual changed plugin. Replace <plugin-slug> before executing:

wp plugin check <plugin-slug>

The article's wp plugin check meu-plugin uses meu-plugin as an example slug, not a fixed target. A source directory can also be checked with wp plugin check /actual/path/to/plugin within a working WordPress environment.

For structured findings, use wp plugin check <plugin-slug> --format=json when supported. Keep errors and warnings visible; do not add exclusions or ignore flags just to make validation pass. Record the command, target, scope, output, and execution failures.

WP-CLI runs static checks by default. Runtime checks also require the target plugin to be installed and active on the local test site. Verify its activation first:

wp plugin is-active <plugin-slug>

If inactive, activate it when local environment setup is authorized: wp plugin activate <plugin-slug>. Otherwise, report runtime checks as not run and label the result static-only. Loading PCP's cli.php alone does not guarantee runtime coverage.

To include runtime checks in a suitable local site, load PCP's actual cli.php before WordPress loads:

wp plugin check <plugin-slug> --require=/actual/path/to/plugin-check/cli.php

Resolve the installed Plugin Check directory instead of assuming the default content directory. If the loader is missing or runtime initialization fails, report that limitation; a static-only result must not be described as runtime validation.

3. Interpret findings before fixing

For each actionable finding, report:

  • Rule/code, severity, and file/line when provided.
  • Why the rule exists and what the source code actually does.
  • Whether it applies, including evidence for any possible false positive.
  • The smallest appropriate correction and any effect on plugin behavior.

Distinguish automated best-practice findings from directory-policy violations; cite the relevant guideline only when it applies. Do not mechanically remove warnings or trust a suggested fix without checking context.

For review-only requests, return the analysis and proposed fixes without modifying the plugin. When fixes are already authorized, apply relevant corrections within that scope without requiring another approval for each finding. Surface uncertain or out-of-scope changes for review.

Optional AI review context

If the installed Plugin Check version includes a prompts/ directory, read relevant prompts as supplementary review criteria alongside the plugin source and task context. Their availability varies; they do not replace the manual checklist or actual check results.

wp plugin check <plugin-slug> --ai is optional. Use it only when installed command help confirms support and the provider setup and use are already authorized. Otherwise, interpret the regular output in the current agent session. Treat AI suggestions about false positives as hypotheses requiring source evidence, not automatic grounds to dismiss findings.

4. Review, retest, and report

After fixes, inspect the diff, rerun affected tests, and repeat Plugin Check with the same target and coverage so results are comparable. Verify affected behavior locally, including permissions and data handling when relevant. Stop when relevant findings are resolved or remaining items have an explicit explanation or blocker; avoid repeated runs without a change or a new diagnostic purpose.

Report the target, actual commands, static/runtime coverage, test results, fixes, remaining findings with rule/code and file/line when available, and checks not performed. Separate a clean Plugin Check result from functional test results and manual policy conclusions. Leave sufficient evidence for human review.

Sources

Source: SKILL.md on GitHub

No rule matched.

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.

No alerts1mo3 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    This skill serves as an authoritative reference for reviewing WordPress plugins against the official WordPress.org Plugin Directory guidelines. It contains no executable code, network operations, or security risks, and all external references point to trusted domains.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

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

Last checked against GitHub last week.

Activeupdated last month
Other metadata
compatibility
Targets WordPress 7.0+ (PHP 7.4.0+). Automated validation requires a local WordPress environment, WP-CLI, and Plugin Check.
  • wordpress
  • gpl
  • licensing
  • plugin-compliance
  • trademark
  • wordpress-org
  • php
  • plugin-directory

README badge

README badge for wordpress/agent-skills/wp-plugin-directory-guidelines

Authoritative reference for the 18 WordPress.org Plugin Directory guidelines covering GPL licensing, plugin naming, trademark rules, trialware restrictions, and submission requirements. Use this skill to audit plugins for compliance before WordPress.org submission, verify GPL header validity and license compatibility, or answer questions about what is allowed in the plugin directory.

Generated from the current SKILL.md.

Does this skill cover all 18 WordPress.org Plugin Directory guidelines?
Yes. The skill is an authoritative reference for all 18 guidelines, with detailed checklists and specific procedures for GPL compliance, naming rules, trialware restrictions, and submission requirements.
What license headers does WordPress.org accept?
WordPress.org accepts GPL-2.0-or-later, GPL-3.0-or-later, or GPLv2/GPLv3 or later formats, with a corresponding License URI header pointing to the GPL text.
Does this help identify why a plugin was rejected from WordPress.org?
Yes. The skill guides you through the 18-guideline checklist to identify common violations (GPL incompatibility, trialware patterns, trademark issues, obfuscation) that typically cause rejections.
Can I use MIT or BSD licensed libraries in my WordPress plugin?
Yes, MIT, BSD, ISC, zlib, and Boost are commonly accepted as GPL-compatible. For conditional licenses like Apache-2.0 or MPL-2.0, the skill provides detailed compatibility guidance.
What counts as trialware and violates the guidelines?
The skill includes a trialware checklist covering premium upsells, freemium flows, license checks, and teaser UI. It flags patterns that restrict core functionality based on payment or licensing.

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