WordPress Plugin Readme.txt Optimization Cheat Sheet
Use this cheat sheet with Claude to audit and optimize your WordPress plugin's readme.txt file for maximum discoverability and conversions.
How to Use This Cheat Sheet
Paste this entire document into a Claude conversation along with your current readme.txt file and say:

"Using the WordPress Plugin Readme Optimization Cheat Sheet, please audit my readme.txt and provide specific recommendations to improve rankings and conversions. Show me the before/after for each section."


WordPress.org Ranking Algorithm Summary
The algorithm uses this formula to rank plugins in search results:
Score = text_relevance × 0.375 × log₂(active_installs) × 0.25 × log₂(support_threads_resolved) × 0.25 × √(rating) × freshness_decay × compatibility_decay
What This Means for Readme Optimization:

Text relevance is determined by matching search terms against 7 fields (in order of weight):

Plugin title (HIGHEST WEIGHT - more than all others combined)
Excerpt/short description (SECOND HIGHEST)
Full description (including FAQ and changelog)
Tags (only first 5 are indexed)
Plugin slug
Author name
Contributor names


All search terms must appear somewhere in the readme.txt or the plugin won't show up for that search
Exact phrase matches outrank scattered keywords
Plugins with 0 reviews default to 2.5 stars (ranking penalty)
Updates within 180 days avoid freshness decay penalties
"Tested up to" field must be current to avoid compatibility penalties


Section 1: Plugin Title Optimization
Algorithm Weight: MAXIMUM (More than all other fields combined)
Optimization Rules:
✅ DO:

Put primary keyword at the BEGINNING
Use exact phrases people actually search
Keep under 50 characters (truncates in search results)
Make it descriptive and benefit-focused
Use format: [Primary Keyword] – [Benefit or Differentiator]

❌ DON'T:

Start with "WordPress" (redundant, trademark violation)
Use clever/brand names without keywords (e.g., "SmartForms")
Use vague terms like "Ultimate," "Pro," "Best"
Exceed 50 characters

Good Title Examples:

"Contact Form Builder – Drag & Drop Form Creator"
"Image Optimizer – Compress & Resize Images"
"WooCommerce Product Feed – Google Shopping Integration"
"Backup & Restore – Complete WordPress Backup Plugin"

Title Validation Checklist:

 Primary keyword appears at the beginning
 Keyword matches what users actually search
 Under 50 characters
 Descriptive of actual function
 Doesn't start with "WordPress"

Audit Questions for Claude:

What is the primary keyword users search for in this plugin's category?
Does the current title include that keyword at the beginning?
Is the title under 50 characters?
What would be a more optimized title following the formula?


Section 2: Short Description (Excerpt) Optimization
Algorithm Weight: SECOND HIGHEST (After title)
Character Limit: 150 characters maximum
Optimization Rules:
✅ DO:

Lead with primary keyword (reinforces title)
Focus on benefits, not features
Use active voice
Answer "Why should I click?"
Use format: [What it does] + [Key benefit] + [Differentiator]
Be specific with numbers/results when possible

❌ DON'T:

Waste space on vague claims ("powerful," "easy," "flexible")
Use passive voice
Lead with generic statements
Include claims without specifics ("#1 rated" without context)
Exceed 150 characters

Good Excerpt Examples:

"Create beautiful contact forms with drag-and-drop builder. No coding required. Spam protection included." (116 chars)
"Optimize images automatically on upload. Reduce file size by 70% without quality loss. Works with any theme." (111 chars)
"Backup your entire site in one click. Schedule automatic backups. Restore with a single click." (96 chars)

Excerpt Validation Checklist:

 Starts with primary keyword
 Under 150 characters
 Uses active voice
 Includes specific benefits
 No generic filler words
 Differentiates from competitors

Audit Questions for Claude:

Does the excerpt lead with the primary keyword?
Is it under 150 characters?
Are benefits specific and measurable?
Could a competitor use the exact same words?
What would be a more conversion-focused excerpt?


Section 3: Full Description Optimization
Algorithm Weight: MEDIUM (Indexed for text matching)
Target Word Count: 2,500+ words
Purpose: Capture long-tail search queries
Optimization Rules:
✅ DO:

Write 2,500+ words of comprehensive documentation
Use natural keyword variations throughout
Include extensive FAQ section
Add "How to" sections for common use cases
Document troubleshooting steps
Explain integrations with related products
Use headers (##) liberally for structure
Answer every question users might search

❌ DON'T:

Keyword stuff
Use only brief feature lists
Skip FAQ section
Write in overly technical jargon
Forget to use headers for organization

Section Structure Template:
markdown## Description
[Comprehensive overview with natural keyword variations]

## Key Features
[Detailed explanations, not just bullet points]

## Easy Drag-and-Drop Form Builder
[Explain this feature with searchable terms]

## Spam Protection Features
[Detail how it works]

## How to [Common Use Case 1]
[Step-by-step guide]

## How to [Common Use Case 2]
[Step-by-step guide]

## Integration with [Related Product]
[Explain integration]

## Frequently Asked Questions

### How do I [common search query]?
[Comprehensive answer]

### Why isn't [common problem]?
[Troubleshooting]

## Troubleshooting
[Common issues and solutions]
Description Validation Checklist:

 2,500+ words total
 Primary keyword appears 5-10 times naturally
 Related keywords/variations included
 FAQ section with 10+ questions
 "How to" sections for common use cases
 Troubleshooting section
 Integration guides where applicable
 Uses ## headers for structure
 Answers searchable questions

Audit Questions for Claude:

What is the current word count? (Target: 2,500+)
How many times does the primary keyword appear naturally?
What related search terms are missing?
What FAQ questions should be added based on the plugin's category?
What "how to" sections would capture long-tail searches?
What common troubleshooting queries should be documented?


Section 4: Tags Optimization
Algorithm Weight: LOW (But still indexed)
Critical Rule: ONLY THE FIRST 5 TAGS ARE INDEXED
Optimization Rules:
✅ DO:

Use actual search terms users type
Include product integrations (e.g., "woocommerce")
Mix broad and specific tags
Research what top competitors use
Validate each tag by browsing it on WordPress.org
Use EXACTLY 5 tags (no more, no less)

❌ DON'T:

Use more than 5 tags (ignored + potentially flagged as spam)
Use competitor names as tags (trademark violation)
Use vague category terms nobody searches
Use tags for keywords already in title

Tag Selection Framework:
For each potential tag, ask:

Is this a term users actually search?
Does browsing this tag on WordPress.org show similar plugins?
Is this a product integration users search for?
Do top competitors in my category use this?

Good Tag Examples by Category:
Contact Form Plugin:

contact-form
form-builder
email
lead-generation
gdpr

Image Optimizer:

image-optimization
compression
performance
seo
lazy-load

Backup Plugin:

backup
restore
migration
security
database

Tag Validation Checklist:

 Exactly 5 tags (no more, no less)
 Each tag represents actual search term
 Browsing each tag shows relevant similar plugins
 Mix of broad and specific terms
 Includes relevant product integrations
 No competitor names
 No trademark violations

Audit Questions for Claude:

How many tags are currently listed? (Should be exactly 5)
Which tags represent actual search terms vs. vague categories?
What tags do the top 5 competitors in this category use?
What product integrations should be included as tags?
What would be the optimal 5 tags for this plugin?


Section 5: Changelog Optimization
Algorithm Weight: LOW (But indexed for text matching)
Purpose: Signal active development + keyword reinforcement
Optimization Rules:
✅ DO:

Describe features with searchable terms
Update regularly (every 90 days minimum)
Use descriptive language, not just version numbers
Include relevant keywords naturally

❌ DON'T:

Write minimal entries ("Bug fixes")
Let it go stale (180+ days triggers decay)
Just list version numbers without context

Good Changelog Examples:
❌ Bad:
= 2.1 =
* Bug fixes
* Performance improvements
✅ Good:
= 2.1 =
* Added spam protection with Google reCAPTCHA integration
* Improved email delivery with SMTP configuration options
* Fixed contact form submission issues on mobile devices
* Enhanced drag-and-drop form builder interface
* Added conditional logic for multi-step forms
Changelog Validation Checklist:

 Latest update within past 90 days
 Each entry describes features with keywords
 No generic "bug fixes" without specifics
 Entries use searchable terminology

Audit Questions for Claude:

When was the last update? (Should be within 90 days)
Do changelog entries use descriptive, searchable language?
How can changelog entries be rewritten to include more keywords?


Section 6: Technical Metadata
Fields to Verify:
Tested up to:

 Set to latest WordPress version (or within 1 major version)
 Updates trigger compatibility_decay penalty if outdated

Requires at least:

 Set to reasonable minimum (don't exclude users unnecessarily)

Requires PHP:

 Set to reasonable minimum PHP version

Stable tag:

 Matches latest version in changelog

License:

 Clearly specified (GPL v2+ is standard)

Audit Questions for Claude:

Is "Tested up to" set to the latest WordPress version?
Are version requirements reasonable and current?


Section 7: Screenshots and Assets
Not Indexed by Algorithm BUT Critical for Conversions
Optimization Rules:
✅ DO:

Show the plugin actually working (not just UI)
Demonstrate key features visually
Use descriptive captions with keywords
Include 5-8 screenshots
Show before/after if applicable
Make screenshots clear at 1200px+ width

❌ DON'T:

Skip screenshots entirely
Use low-resolution images
Show only admin screens without context
Write vague captions

Screenshot Caption Template:
Instead of: "Settings page"
Use: "Drag-and-drop form builder interface with spam protection options"
Instead of: "Frontend display"
Use: "Beautiful contact forms displayed on your site with custom styling"
Assets Validation Checklist:

 5-8 high-quality screenshots included
 Screenshots show plugin functionality, not just UI
 Each caption includes relevant keywords
 Banner image is professional and clear
 Icon is recognizable at small sizes


Complete Readme Audit Checklist
Use this for final verification:
Title & Excerpt:

 Title under 50 chars with primary keyword first
 Excerpt under 150 chars with benefit-focused copy
 Both use exact search terms users type

Description:

 2,500+ words total
 Comprehensive FAQ (10+ questions)
 "How to" sections for common use cases
 Troubleshooting section
 Integration guides where applicable
 Uses ## headers for structure

Tags:

 Exactly 5 tags
 All represent actual search terms
 Include relevant integrations
 No competitor names

Technical:

 "Tested up to" is current (within 1 major version)
 Changelog updated within 90 days
 Version numbers consistent

Assets:

 5-8 quality screenshots with keyword-rich captions
 Professional banner and icon


How to Use This Cheat Sheet with Claude
Prompt Template:
I need help optimizing my WordPress plugin's readme.txt file for better rankings and conversions. Please use the "WordPress Plugin Readme Optimization Cheat Sheet" to audit my current readme.txt.

For each section (Title, Excerpt, Description, Tags, etc.), please:
1. Identify what's currently working well
2. Identify specific issues or missed opportunities
3. Provide before/after recommendations
4. Explain why each change will improve rankings or conversions

Here is my current readme.txt:

[PASTE YOUR README.TXT HERE]

Please be specific with your recommendations and show me exactly what the optimized version should look like.

Common Optimization Patterns
Pattern 1: Keyword-Deficient Title
Problem: Generic or branded title without search keywords
Example: "SmartForms Pro"
Fix: "Contact Form Builder – Drag & Drop Form Creator"
Impact: Makes plugin discoverable for "contact form builder" searches
Pattern 2: Vague Excerpt
Problem: Generic benefits without specifics
Example: "A powerful and easy-to-use form plugin for WordPress."
Fix: "Create beautiful contact forms with drag-and-drop builder. No coding required. Spam protection included."
Impact: Converts browsers into clickers with specific benefits
Pattern 3: Minimal Description
Problem: 200-word description with basic feature list
Fix: 2,500+ word comprehensive guide with FAQ, how-tos, troubleshooting
Impact: Captures long-tail searches like "how to add contact form to sidebar"
Pattern 4: Too Many Tags
Problem: 15 tags listed (only first 5 indexed)
Fix: Carefully selected 5 tags based on search volume and competitor research
Impact: Focuses tag value on most important terms
Pattern 5: Stale Changelog
Problem: Last update 8 months ago
Fix: Update to latest WordPress version, commit minor changes every 90 days
Impact: Avoids freshness_decay ranking penalty

Success Metrics
After optimization, track these metrics to measure improvement:
Immediate (1-7 days):

Search impressions for primary keywords
Click-through rate from search results
Position in search for primary keywords

Short-term (30-60 days):

Daily active installs
Total active installs
Search ranking position changes

Long-term (90+ days):

Review acquisition rate
Average rating improvement
Support thread volume and resolution


Red Flags to Avoid
These will hurt your rankings or get you banned:
❌ Never:

Keyword stuff (using keywords unnaturally/excessively)
Use competitor names in slug, title, or tags
List more than 5 tags
Let plugin go 180+ days without updates
Use generic placeholder content
Copy competitors' descriptions verbatim
Make false claims about features
Use bait-and-switch tactics in descriptions


Final Note
This cheat sheet is based on:

WordPress.org's disclosed ranking algorithm (2017 Elasticsearch implementation)
Analysis of top-ranking plugins across categories
WordPress.org official documentation and guidelines
Real-world optimization case studies

The algorithm prioritizes plugins that:

Match search queries accurately (text relevance)
Are actively maintained (freshness)
Have strong user satisfaction (ratings)
Provide good support (resolution rate)
Have proven usage (active installs)

Your readme.txt controls #1 (text relevance) directly and influences #2 (freshness through changelog). Optimizing it well sets the foundation for everything else.