At 11:17 on 18 November I committed a change to one of our WooCommerce plugins on WordPress.org. It touched readme.txt and nothing else — no PHP, no version number, no release. The whole of it was one line:
-Tags: cpf, cnpj, cep, brasil, brazil
+Tags: cpf, cnpj, cep, brasil, validar cpf
Before that commit, a WordPress.org search for validar cpf did not contain the plugin anywhere in the first 200 results. Ten hours later it was 4th out of 9. Thirteen hours later it was still 4th, so this was not a blip in the index. The tag I spent to get there, brazil, had 602 competing plugins and had us sitting 150th — page sixteen, which is the same as nowhere.
That is the useful half of what I learned. The other half is that fourth place out of nine is not a lot of weather, and I want to be honest about which half is bigger.
Five slots, and we were spending them on lottery tickets
A plugin readme gives you five tags. The directory treats them as search terms, and every plugin author inherits the same instinct: fill them with the biggest words you can think of. Here is what the biggest words actually cost, measured against the public plugins API rather than guessed:
| Term | Plugins competing | Our rank |
|---|---|---|
menu | 10,000 | not in the top 200 |
woocommerce invoice | 1,779 | not in the top 200 |
qr menu | 1,133 | not in the top 200 |
restaurant | 919 | not in the top 200 |
brazil | 602 | 150th |
validar cpf | 9 | 4th |
Measured 19 November 2026 with a 40-line script over api.wordpress.org/plugins/info/1.2/. Zero failed queries — which matters, because a request that errors and a term you genuinely do not rank for both print as a blank. One wrinkle worth reporting rather than smoothing: the API gives the count for validar cpf as 9 and then returns 8 plugins, so the room is even smaller than the number says.
And the competition on a broad tag is not even competition for the same thing. The first three results for brazil on the day I measured were complianz-gdpr, a shipping calculator, and gtranslate — a cookie-consent plugin and a translation plugin, neither of which is about Brazil. That is what 602 results means: the word is a crowd, not an audience.
Three of those words were in our readmes for a month. A tag with 10,000 competitors is not a search term, it is a raffle, and menu was also redundant with restaurant and qr-menu in the same list. We had five slots and were using at least two of them to lose slowly.
So the trade works. Now the part that spoils it
Validar cpf has nine competitors. That is not an underserved niche we cleverly spotted. It is an empty room, and it is empty because almost nobody walks into it. The rank is real and the traffic behind it is bounded by how rare the search is — those are the same fact seen from two ends.
To find out whether any of this mattered, I had to know what normal looks like, and the first attempt at that got it wrong in a way worth repeating. I compared our plugins against others with a similar number of cumulative downloads. But downloads are rate multiplied by age, so banding a cohort on the total quietly removes the fast young plugins — the ones you are actually competing with — and keeps the slow old ones. It flattered us by roughly 25 percentile points.
Matching on age instead: I paged the directory’s own browse=new listing for 6,997 plugins and kept the 5,304 added between 14 and 57 days ago, the same bracket as ours. Zero failed requests.
| Plugins added 14–57 days ago (n = 5,304) | Downloads per day |
|---|---|
| Cohort median | 8.36 |
| Cohort p25 / p75 | 5.62 / 15.00 |
| Our invoice plugin (483 downloads, 52 days) | 9.29 — 56th percentile |
| Our restaurant plugin (254 downloads, 23 days) | 11.04 — 64th percentile |
| Our Brazilian checkout plugin (257 downloads, 38 days) | 6.76 — 38th percentile |
Two more numbers from that cohort explain why I stopped treating our dashboard as a diagnosis. 91.3% of those 5,304 plugins report active_installs of 0, which on WordPress.org means “fewer than 10”. 7.3% have a single rating. All three of ours report zero installs and zero ratings, and I had been reading that as a defect to fix. It is the median condition of a plugin that is one or two months old.
Which lands the whole experiment in an awkward place, and the awkwardness is the point: we were already an ordinary new plugin before any of the tag work, and the terms the tag work can win are small by construction. Both things are true. Readme edits are free, reversible, land within a day and demonstrably move the directory. They are also not going to be the reason anyone pays us.
The confound in my own experiment
I would rather point this out than have you find it. That commit did two things, not one. It swapped the tag, and it added a Portuguese sentence to the description. So I have a second data point from the same ten hours: campos brasileiros, a phrase that appears only in the prose and in no tag slot, also went from absent to 12th of 27.
It is tempting to read that pair as proof that the tag field outranks the description — 4th from a tag, 12th from a sentence. It is not proof. The two terms have different competition (9 against 27), and both fields changed in the same revision, so the tidy explanation and the boring one fit equally well. The clean test is to trade exactly one tag and change nothing else, and I have not run it.
There is also a waiting cost that is easy to misread. Two more readme trades went up last night, three and two hours before I started measuring, and both are still absent from their new terms. That is not a null result, that is an index that takes about half a day. The number that decides whether they worked does not exist yet.
What I would tell someone with a new plugin
Price a tag before you spend it. The plugins API will tell you how many plugins match a term and where you sit in that order, for free, in about forty lines. Guessing at the demand for a word is the step everyone skips, including us for a month.
Count your failures next to your zeroes. Five of my own API lookups came back blank because a shell ate the brackets in request[slug], and an empty result reads exactly like a plugin that is not there. One of those is a finding and the other is your own tooling lying to you.
Match a cohort on age, never on a total. Anything cumulative — downloads, revenue, signups — is a rate times a clock, and selecting on it selects for the clock.
Then go and look at where the money is searching. Our own Search Console, for the 90 days to 17 November, records 1,631 impressions and 7 clicks across this whole site. The eight pages about our plugins account for 101 of those impressions and one of the clicks. A free Eventbrite fee calculator we wrote as a throwaway took 99 impressions by itself, at an average position of 42. Directory ranking is cheap and worth doing. It is not a substitute for a reason to buy.
What we do not know
Whether any of it produced a single install. active_installs is bucketed, so every number under 10 reports as 0 — a tag trade could have won us nine users and the figure would not move. downloaded counts mirrors, bots and update checks alongside humans. The browse=new listing is the directory’s own, and I cannot verify that it enumerates every plugin added in the window, only that it returned 6,997 of them with no errors. And one trade cannot tell me whether WordPress.org weights the tag field above the description at all.
What I can say is narrow and measured: a readme-only commit, costing nothing and risking nothing, moved a plugin from outside the top 200 to 4th within ten hours, and held. If you have five tag slots full of words with four figures of competition, that is a free afternoon with a result you can check the next morning. Just do not expect the result to be customers.
The plugin in question is Brazilian Checkout Fields for WooCommerce, which validates CPF and CNPJ by check digit and fills an address from a CEP. The rest are on our plugins page, download counts and all.
