Why Your Plugin Readme Is Killing Your Downloads

There are 60,000+ plugins in the WordPress.org directory. Most of them will never break 100 active installs. Most of their developers will assume it’s because nobody wants what they built.

That’s rarely the reason.

The more common reason is a readme.txt that looks fine from the outside but is functionally invisible to the algorithm that decides who gets found. The developer built something real, wrote a description, pushed to SVN, and waited. And nothing happened. Not because the plugin was bad — because the readme was written like a product brochure when it needed to be written like a search document.

I’ve been through this. Building WhoKnew Directory SEO™ forced me to dig into exactly how WordPress.org’s search algorithm scores plugin listings — not from guesswork, but from the actual open-source code that runs the directory. What I found explains why so many genuinely good plugins sit on page eight while mediocre ones with optimized readmes rank on page one.

Here’s what’s actually happening, and what to fix.

The Algorithm Is Open Source. Most Developers Never Look at It.

WordPress.org’s plugin directory runs on WordPress, and the search logic is licensed under the GPL — meaning anyone can read it. The ranking algorithm operates in two phases.

Phase one pulls a candidate set of plugins that match the query. It looks for your search terms across several fields: plugin title, slug, tags, short description, and the long description. Plugins where the search term doesn’t appear in any of these fields don’t make the candidate set at all — they’re invisible for that query no matter how many installs they have.

Phase two scores and ranks everything in that candidate set. This is where most developers get hurt. The scoring factors include active install count, rating, support resolution rate, whether the plugin is compatible with recent WordPress versions, and how your keyword appears across the fields. A match in the title scores higher than a match in the description. A match in the slug scores higher than a match in the tags.

The practical implication: if your plugin doesn’t appear in phase one for the searches your users are actually running, nothing in phase two matters. You’re not ranked low. You don’t exist for that query.

The Title Is Where Most Developers Make Their First and Biggest Mistake

Developers name their plugins the way they name their companies: brand only. The readme title becomes “Acme Pro” and the plugin ships. It ranks for “Acme Pro.” It ranks for nothing else.

The plugin title is the highest-weighted field in the WordPress.org search algorithm. A keyword match in the title carries more scoring weight than the same keyword in the description, the tags, or anywhere else. This means your title isn’t just a name — it’s your most valuable piece of SEO real estate on the entire listing.

There’s an important line to understand here. WordPress.org’s Guideline #12 explicitly prohibits keyword stuffing in readmes — and that includes titles. Cramming a string of search terms into your plugin name is a violation that can get your plugin closed. The goal isn’t to stuff keywords into a title. The goal is to write a title that genuinely and accurately describes what your plugin does.

Those two things aren’t in conflict. A title like “Acme Pro” tells no one anything. A title like “Contact Form Builder by Acme Pro” is accurate, human-readable, and happens to contain the term people search for. That’s not stuffing — that’s just a descriptive name.

The distinction matters because WordPress.org is actively flagging titles that read like keyword lists — “Contact Forms, Payment Forms, Surveys & More by Acme Pro” is the pattern that draws scrutiny. One clear, accurate functional description is what you want. Not a list. Not repetition. Just a name that tells someone exactly what they’re installing.

You can verify what’s working by searching for any competitive plugin category and reading the titles of the top five legitimate results. The ones that have been around longest and rank well tend to have clean, descriptive names — not paragraph-length keyword strings.

The Short Description Gets 150 Characters. Most Readmes Waste Them.

The short description is the line that appears directly under the plugin title on the listing page and in WordPress admin search results. It gets 150 characters — no more, or it gets cut. No markup.

It also feeds directly into the algorithm’s phase one candidate matching. If your target keywords don’t appear in either the title or the short description, you’re relying entirely on the long description and tags to get into the candidate set. That’s a weaker signal.

Most short descriptions read like taglines: “The most powerful plugin for your WordPress site!” That description matches zero searches. It uses up all 150 characters saying nothing that the algorithm — or a potential installer — can act on.

A well-written short description front-loads the primary use case in plain language. If someone searches for “block spam bots WordPress,” your short description should contain those words or close variants. Treat it like a meta description for a high-stakes Google result, because functionally, that’s what it is.

Tags: Five Is the Real Number, Not Twelve

The WordPress.org documentation allows up to twelve tags. What the documentation doesn’t emphasize clearly enough: only the first five tags affect the directory’s internal search rankings. Tags six through twelve are visible to external search engines indexing the readme file, but they have no effect on WordPress.org’s own search algorithm or category listings.

This matters because most developers either stuff as many tags as possible (diluting the signal) or pick whatever seems relevant without thinking about search volume. Both approaches underperform.

The correct approach is to identify the five highest-volume keyword phrases that describe what your plugin does, verify that people actually search for them by checking competing plugins that rank for those terms, and use exactly those five. No more. That’s your full tag budget, and you want every cent of it working.

The Rating Penalty Nobody Talks About

If your plugin has no ratings, the WordPress.org algorithm doesn’t treat it as unrated. It treats it as if it has a 2.5-star average.

This comes directly from the directory’s search code. A plugin with zero reviews gets a default score that puts it on par with a plugin that has been rated poorly. The algorithm interprets absence of ratings as evidence of mediocrity, not newness.

The practical consequence: every new plugin launch is competing against the equivalent of a 2.5-star handicap from day one. The only way out of it is to get rated. Even a single five-star review significantly changes your scoring position in the algorithm.

Getting that first review isn’t gaming the system — it’s correcting a structural disadvantage that the algorithm itself creates for new plugins. Ask your beta users. Ask the colleagues who tested it. Ask anyone who installed the free version and got value from it. One honest five-star review moves the needle more than most readme optimizations will.

Support Resolution Is a Ranking Signal. Responding Isn’t Enough.

This is the one that catches most developers off guard. WordPress.org tracks your support thread resolution rate and factors it into the search ranking algorithm. Developers know they should answer support threads — but many answer them without ever marking the ticket as resolved.

From the algorithm’s perspective, an answered but unresolved thread counts against you the same way an ignored one does. The resolution status is what the algorithm reads, not the presence of a reply. You can answer every single support thread promptly and still take a ranking penalty if you’re not marking threads as resolved after the issue is addressed.

The fix is a two-minute habit: when a support thread reaches a natural conclusion — either the user confirms it’s solved, you’ve provided the answer, or the thread has gone quiet — mark it resolved. Do it consistently, and your support resolution percentage climbs. That number feeds directly into how the algorithm scores you relative to competing plugins.

The “Tested Up To” Field Is a Quiet Ranking Factor

WordPress.org tracks whether your plugin is flagged as tested against a recent version of WordPress core. A plugin that shows it’s only tested up to a version several releases behind the current stable gets a lower compatibility score in the algorithm — even if the plugin actually works fine on the current version.

This is a five-minute fix that many developers forget for months at a time. After every major WordPress release, update your “Tested up to” field in the readme header and push the update. You don’t have to ship new features. You don’t even have to change anything in the code. Just update the field, increment the version, and push. The algorithm rewards plugins that signal active maintenance, and this is the lowest-effort signal available.

The Long Description Is Your Conversion Page, Not a Feature List

Most long descriptions read like changelog entries: a bulleted list of features with no context, no problem framing, and no reason for someone to install. This is a missed opportunity on two fronts — it’s bad for conversions and it’s underutilizing the keyword real estate available to you.

The long description is the only field in your readme with no character limit. It supports Markdown. It surfaces in algorithm phase one candidate matching. And it’s the page a skeptical developer reads when they’re deciding whether to install your plugin or the competitor’s.

A well-structured long description opens with the problem it solves — in the same language the user was searching when they found it. It describes the solution in plain terms before getting into feature specifics. It uses subheadings that naturally include secondary keywords. And it closes with a clear picture of who the plugin is for.

The Readme Audit: What to Check Right Now

If you have a plugin live on WordPress.org and installs are lower than they should be, run through this checklist before changing anything else:

1. 1
   Does your title lead with keywords? Search for the terms you want to rank for. If the top results don’t look like your title format, rewrite the title to match the pattern of what’s actually ranking.
2. 2
   Does your short description contain your primary keyword phrase? It should appear in the first sentence, naturally. If it doesn’t, it doesn’t belong in the short description.
3. 3
   Are your first five tags the highest-volume descriptive terms for your plugin? Not your brand name, not your plugin’s unique feature names — the generic terms people search for when they have the problem your plugin solves.
4. 4
   Do you have at least one review? If not, your priority above readme optimization is getting that first review. Everything else compounds once you’re above the 2.5-star default.
5. 5
   Is “Tested up to” current? Check the latest stable WordPress version and make sure your readme reflects it.
6. 6

   What is your support resolution percentage? Check your WordPress.org plugin page. If it’s below 80%, start working through open threads and marking them resolved before touching your readme.

Tracking Whether Your Changes Are Working

One of the more frustrating aspects of WordPress.org SEO is the lack of native ranking data. The directory doesn’t show you where you rank for any given keyword, how your position has changed after a readme update, or how competitors are positioned relative to you.

This is the exact problem WhoKnew Directory SEO™ was built to solve. It tracks your live keyword positions on WordPress.org, scores your readme coverage across all seven indexed fields, and surfaces every keyword a competitor ranks for that your listing doesn’t — so you can close the gaps systematically rather than guessing. The AI Optimizer generates a ready-to-paste prompt pre-loaded with your current readme, your coverage gaps, and competitor benchmarks, which you paste into any AI to get a fully rewritten readme back in minutes.

Most plugin developers make one round of readme changes and move on. The ones who consistently grow their install base treat the readme as a living document — checking rankings, identifying new gaps as the competitive landscape shifts, and iterating. That requires data. You can read more about how the algorithm scores your listing in The 7 Fields WordPress.org Actually Indexes and get the full strategic picture in How to Rank Your Plugin on WordPress.org.

If you want to see where you currently stand before changing anything, spying on the keyword strategy of competitors who outrank you is the fastest way to understand the gap. And if your plugin is already past the readme stage and you’re looking at organic install growth, why good plugins fail to get downloads covers the full picture beyond the readme itself.

Who knew a text file you wrote once and forgot about was the reason your plugin never got found.