How Many Keywords Should a Plugin Readme Target?

Target 5 to 8 distinct keywords across your entire readme.txt — not 20, not 1. Split them across three fields with different weight: 1-2 primary terms in your short description, up to 12 tags (but only your top 5-8 actually earn their slot), and 2-4 secondary or long-tail terms worked naturally into the description body. Go past that and you're not adding reach, you're diluting relevance signals and risking a review-team flag.

How Many Keywords Should a Plugin Readme Target in Practice?

The honest number depends on field, not a single global count. The WordPress.org plugin directory doesn't treat your readme as one blob of text — it reads specific fields with specific weight, and keyword-stuffing one field (usually tags) is the single most common readme mistake developers make while trying to rank for every variant of their core term.

A plugin targeting "form builder" shouldn't also chase "contact form," "email form," "survey form," "popup form," and "booking form" in the same tags line. Pick the 2-3 terms that actually describe what the plugin does, and let the description body carry supporting variants in natural sentences.

Where Keywords Actually Live in readme.txt

Before you decide how many keywords to target, know which fields WordPress.org's search actually reads and how much real estate each gives you.

Tags and the short description do the heaviest lifting for WordPress plugin rankings in directory search. The body matters more for how your listing reads to a human deciding whether to install, and increasingly for how AI answer engines summarize what your plugin does.

The Keyword Budget: A Field-by-Field Breakdown

Primary keyword (1 term)

This is the term you'd want to rank for if you could only pick one — "cache plugin," "form builder," "membership plugin." It belongs in your slug if you're still naming the plugin, your short description, and your first tag.

Secondary keywords (2-3 terms)

Close variants or feature-specific terms a user might search instead — "page cache," "lazy loading," "CDN integration" for a caching plugin. These go in tags and get a sentence each in the description.

Long-tail keywords (2-4 terms)

Specific, lower-competition phrases tied to a use case — "WooCommerce cache compatibility," "cache plugin for shared hosting." These rarely belong in tags; they work better as natural phrasing inside FAQ sections or feature lists, where they also help with featured-snippet pickup on Google.

Add those up and you land at 5-8 keywords doing real work, which is why that's the number to plan around rather than a round figure pulled out of thin air.

Why Overloading Tags Backfires

WordPress.org's plugin review team actively checks for tag spam — irrelevant or excessive tags unrelated to plugin function are a flaggable guideline violation, and plugins have had updates rejected over it. Padding tags with every keyword variant you can think of isn't a gray area; it's a documented way to get your listing held up.

There's also a diminishing-returns problem independent of enforcement. If your tags read "seo, wordpress seo, best seo plugin, seo optimization, rank higher, google ranking, meta tags," the algorithm has no clean signal for what the plugin actually is. A tighter list — "seo, xml sitemap, meta tags, schema, open graph" — tells both the algorithm and the human reading your listing exactly what they're getting.

Tags vs. Keywords — Not the Same Fight

Tags and keywords get used interchangeably in most advice, but they're different jobs. Tags are a structured field with a cap; keywords are the broader set of terms you want your readme to be relevant for, including ones that never appear as literal tags. We go deep on this distinction, including which one WordPress.org search actually prioritizes, in Plugin Tags vs Keywords on WordPress.org: What Matters.

The short version: tags are for directory search, keywords are for everything else — your description copy, your support forum answers, your changelog language, and increasingly how AI tools describe your plugin when asked for recommendations.

How to Pick the Right Keywords

Don't guess. Pull actual search volume and difficulty data from a keyword research tool before you lock in your tag list — the term you assume is highest-volume is often beaten by a less obvious variant.

Then check what's already ranking. Run a competitor analysis against the top 5-10 plugins in your category to see which tags and phrases they're using in their own readmes, and use the plugin & theme detector to see which plugins are actually installed on sites ranking for your target terms — installed-base data is a stronger relevance signal than readme copy alone.

Look at how established plugins balance this. Yoast SEO keeps its tag list tight around core function (seo, xml sitemaps, schema) rather than chasing every SEO-adjacent phrase, and it still dominates its category's rankings.

Step-by-Step: Building Your Keyword Set

1. Write down the single sentence that describes what your plugin does — your primary keyword usually falls out of that sentence.
2. Pull 10-15 keyword candidates from a keyword research tool, filtered to WordPress-specific search intent.
3. Cut the list to your top 5-8 based on relevance to actual plugin function, not just volume.
4. Assign 1-2 to the short description, up to 8 to tags, and work the rest into description headers and FAQ copy.
5. Re-check your competitor analysis data every 6-12 months — category keyword trends shift as new plugins launch and old ones get retired.

Common Mistakes That Waste Your Keyword Budget

• Tag duplication of the plugin name. If your plugin is called "Simple Form Builder," you don't need "form builder" repeated three different ways in tags.
• Ignoring the short description entirely. It's your highest-weight, most-wasted field — most readmes leave it generic ("the best plugin for X") instead of keyword-loaded and specific.
• Treating readme SEO as separate from site SEO. The same relevance principles covered in WordPress SEO: The Mechanics That Actually Move Rankings apply to directory listings too — relevance and specificity beat raw keyword volume.
• Never revisiting the list. A keyword set that worked at launch goes stale as competitors like Elementor or WooCommerce-adjacent plugins shift their own positioning.

Frequently Asked Questions

How many tags can I add to a WordPress plugin readme?

WordPress.org allows up to 12 comma-separated tags in the readme's Tags field, but only your top 5-8 most relevant tags carry real search weight. Padding the rest with low-relevance variants doesn't add reach and can trigger a review-team flag for tag spam.

Does keyword stuffing in a plugin readme get flagged?

Yes. The WordPress.org plugin review team checks for tags and description content that don't match actual plugin function, and excessive or irrelevant keyword repetition is a documented guideline violation that can hold up an update or get assets rejected.

What's the difference between plugin tags and keywords?

Tags are a structured, capped field used specifically by WordPress.org's directory search algorithm. Keywords are the broader set of terms you want associated with your plugin across tags, short description, body copy, and even support forum answers — see Plugin Tags vs Keywords on WordPress.org: What Matters for the full breakdown.

Where should my main keyword go in a plugin readme?

Put your single primary keyword in the short description (the ~150-character field shown in search results and the plugin list), and echo it as the first tag. These two fields carry the most search weight after the plugin name itself.

Can I change my plugin's keywords after it's published?

Yes — tags, short description, and body copy can all be updated anytime you push a readme change with a new version, and WordPress.org re-indexes it. There's no penalty for revising keyword targeting as you learn what search terms actually drive installs.

Do readme keywords affect Google rankings, or only WordPress.org search?

Primarily WordPress.org's internal directory search, since your readme page is on wordpress.org, not your own domain. That said, well-chosen terms in your plugin's description still influence how AI answer engines and Google's indexed version of your plugin page describe it, so it's not purely an internal-search exercise.

Should every plugin use the full 12 tags?

No. Use as many tags as you have genuinely relevant terms for — often that's 5-8, not 12. Filling unused tag slots with loosely related terms just to hit the cap dilutes relevance rather than adding coverage.