claude-plugin-wordpress-manager 2.4.0 → 2.9.0

package/skills/wp-content-optimization/references/headline-optimization.md

@@ -0,0 +1,171 @@
+# Headline Optimization
+
+## Overview
+
+Headlines are the single most impactful element for both search CTR and on-page engagement. Claude performs headline analysis by evaluating keyword placement, emotional impact, clarity, length, and formula adherence — then generates scored alternatives. No external headline analyzer APIs are needed.
+
+## Headline Scoring Criteria (1-10 Scale)
+
+| Score | Criteria | Weight |
+|-------|----------|--------|
+| 0-2 | Keyword presence (primary keyword in title) | 20% |
+| 0-2 | Power word usage (emotional/urgency/curiosity) | 20% |
+| 0-2 | Length optimization (50-60 chars for SEO, 6-12 words) | 20% |
+| 0-2 | Clarity and specificity (reader knows what to expect) | 20% |
+| 0-2 | Formula adherence (matches proven headline pattern) | 20% |
+
+### Score Interpretation
+
+| Score | Rating | Action |
+|-------|--------|--------|
+| 9-10 | Excellent | No changes needed |
+| 7-8 | Good | Minor tweaks for improvement |
+| 5-6 | Average | Rewrite recommended |
+| 3-4 | Below Average | Rewrite required |
+| 1-2 | Poor | Complete headline overhaul |
+
+## Power Word Categories
+
+### Emotional Words
+- Trust: proven, guaranteed, authentic, certified, trusted
+- Fear: warning, dangerous, mistake, avoid, never
+- Joy: amazing, incredible, brilliant, stunning, remarkable
+- Surprise: secret, shocking, unexpected, little-known, hidden
+
+### Urgency Words
+- Time: now, today, immediately, hurry, limited, deadline
+- Scarcity: exclusive, rare, only, last chance, while supplies last
+- Action: act, rush, grab, claim, don't miss
+
+### Curiosity Words
+- Mystery: secret, hidden, little-known, underground, insider
+- Question: why, how, what if, did you know, ever wonder
+- Incomplete: the real reason, what nobody tells you, the truth about
+
+### Value Words
+- Benefit: free, save, boost, increase, maximize, transform
+- Ease: simple, easy, quick, effortless, step-by-step, beginner
+- Authority: ultimate, complete, definitive, comprehensive, expert
+
+## Headline Formulas
+
+### How-To Formula
+```
+How to [Achieve Desired Result] [Without Undesired Outcome]
+```
+Examples:
+- "How to Optimize WordPress Speed Without Plugins"
+- "How to Write SEO Headlines That Actually Get Clicks"
+
+### List Formula
+```
+[Number] [Adjective] [Keyword] [Promise/Benefit]
+```
+Examples:
+- "7 Proven Ways to Improve Your WordPress Page Speed"
+- "15 Essential WordPress Plugins for Small Business"
+
+### Question Formula
+```
+[Question Word] [Keyword] [Intriguing Element]?
+```
+Examples:
+- "Why Is Your WordPress Site So Slow? (And How to Fix It)"
+- "What Makes the Best WordPress Themes Actually Convert?"
+
+### Comparison Formula
+```
+[Option A] vs [Option B]: [Decisive Factor]
+```
+Examples:
+- "Yoast vs Rank Math: Which SEO Plugin Actually Performs Better?"
+- "WooCommerce vs Shopify: The Complete 2026 Comparison"
+
+### Result Formula
+```
+[Action] That [Specific Result] in [Timeframe]
+```
+Examples:
+- "WordPress Caching Setup That Cuts Load Time by 60% in 10 Minutes"
+- "SEO Fixes That Doubled Our Organic Traffic in 30 Days"
+
+## Keyword Placement Rules
+
+1. **Front-load the keyword** — primary keyword in the first 3-4 words
+2. **Natural phrasing** — keyword must read naturally, not forced
+3. **Exact match first** — try exact keyword match; partial match as fallback
+4. **Avoid keyword stuffing** — keyword appears once in the headline
+5. **Brand at the end** — if including brand name, use pipe separator at end
+
+### Examples
+```
+Good: "WordPress Speed Optimization: 10 Proven Techniques"
+       ^ keyword at front
+
+Bad:  "10 Proven Techniques for Making Your WordPress Website Speed Faster"
+       ^ keyword buried, awkward phrasing
+```
+
+## A/B Title Generation Workflow
+
+### Step 1: Fetch Current Title
+```
+Use list_content to get the current post title and slug.
+```
+
+### Step 2: Analyze Current Title
+Claude evaluates the title against the scoring criteria above and assigns a score.
+
+### Step 3: Generate 3 Alternatives
+Claude generates three headline variants using different formulas:
+- Variant A: Same formula, optimized (improve power words, keyword placement)
+- Variant B: Different formula (e.g., if original is How-To, try List)
+- Variant C: Curiosity-driven variant (question or result formula)
+
+### Step 4: Score All Variants
+Each variant receives a 1-10 score with per-criteria breakdown.
+
+### Step 5: Apply Best Option
+```
+Use update_content to set the winning title.
+Track the change for future CTR comparison via GSC data.
+```
+
+## Example Workflow
+
+### Input
+```
+Current title: "Tips for WordPress"
+Target keyword: "WordPress performance optimization"
+```
+
+### Analysis
+```
+Score: 2/10
+- Keyword presence: 0/2 (target keyword missing)
+- Power words: 0/2 (none)
+- Length: 0/2 (too short — 3 words)
+- Clarity: 1/2 (vague, no specificity)
+- Formula: 1/2 (implied list, but no number)
+```
+
+### Generated Alternatives
+```
+Variant A (List):     "9 WordPress Performance Optimization Tips That Actually Work" → 8/10
+Variant B (How-To):   "How to Master WordPress Performance Optimization in 2026" → 7/10
+Variant C (Result):   "WordPress Performance Optimization: Cut Load Time by 50%" → 9/10
+```
+
+### Recommendation
+Apply Variant C — highest score, strong keyword placement, specific result promise, power word ("cut"), appropriate length (56 chars).
+
+## Best Practices
+
+- Always preserve the primary keyword when rewriting headlines
+- Test one title change at a time to measure impact via GSC CTR data
+- Wait 2-4 weeks after title change before evaluating CTR impact
+- Keep headline under 60 characters for full display in search results
+- Use numbers when possible (odd numbers perform slightly better)
+- Front-load the most important information
+- Avoid clickbait — headline must accurately represent content
+- Consider the search intent behind the target keyword when choosing formula

package/skills/wp-content-optimization/references/meta-optimization.md

@@ -0,0 +1,243 @@
+# Meta Description and Title Tag Optimization
+
+## Overview
+
+Title tags and meta descriptions are the first impression users see in search results. Optimizing these elements directly impacts click-through rate (CTR). Claude generates optimized meta elements by combining best practices with GSC CTR data, then produces A/B variants for testing. This process uses existing WP REST Bridge and GSC tools — no additional APIs needed.
+
+## Title Tag Best Practices
+
+### Rules
+
+| Rule | Standard |
+|------|----------|
+| Maximum length | 60 characters (Google truncates at ~60) |
+| Keyword placement | Primary keyword in the first 3-4 words |
+| Uniqueness | Every page must have a unique title |
+| Brand inclusion | Optional, at end with pipe separator |
+| Keyword repetition | Keyword appears once only |
+| Readability | Must make sense as a standalone phrase |
+
+### Title Tag Formula
+```
+[Primary Keyword] — [Benefit or Differentiator] | [Brand]
+```
+
+### Character Count Optimization
+```
+Ideal:   50-60 characters (full display in all search results)
+OK:      40-50 characters (may look short but fully visible)
+Warning: 60-65 characters (partial truncation on some devices)
+Error:   65+ characters (truncated, meaning lost)
+Too Short: <30 characters (underutilizing title space)
+```
+
+### Examples
+```
+Good (55 chars): "WordPress Speed Optimization — 10 Proven Techniques | Brand"
+Good (48 chars): "How to Speed Up WordPress in 2026 | Brand"
+Bad (72 chars):  "The Complete and Ultimate Guide to WordPress Speed Optimization Tips 2026"
+Bad (18 chars):  "Speed Tips"
+```
+
+## Meta Description Guidelines
+
+### Rules
+
+| Rule | Standard |
+|------|----------|
+| Maximum length | 155-160 characters |
+| Minimum length | 120 characters (shorter looks incomplete) |
+| Keyword inclusion | Primary keyword once, naturally |
+| Call to action | Include an action verb (learn, discover, get, try) |
+| Uniqueness | Every page must have a unique description |
+| Emotional trigger | Include benefit or pain point |
+| Specificity | Use numbers, data, or specific outcomes |
+
+### Meta Description Formula
+```
+[Action verb] [what the reader gets/learns]. [Specific detail or data point]. [CTA].
+```
+
+### Examples
+```
+Good (152 chars):
+"Learn 10 proven WordPress speed optimization techniques that cut load time
+by 50%. Step-by-step guide with benchmarks. Start optimizing today."
+
+Bad (89 chars):
+"This article is about WordPress speed optimization. Read more on our website."
+
+Bad (185 chars):
+"In this comprehensive and detailed guide we will cover everything you need to
+know about optimizing your WordPress website for speed including caching and
+image optimization techniques."
+```
+
+## Using GSC CTR Data for Optimization
+
+### Identifying Low-CTR Pages
+
+#### Step 1: Pull Page Performance Data
+```
+Use gsc_page_performance to get CTR data for all pages.
+Sort by impressions (descending) to focus on high-visibility pages first.
+```
+
+#### Step 2: CTR Benchmarks by Position
+
+| Average Position | Expected CTR | Below Average |
+|-----------------|-------------|---------------|
+| 1 | 25-35% | <20% |
+| 2 | 12-18% | <10% |
+| 3 | 8-12% | <6% |
+| 4-5 | 5-8% | <4% |
+| 6-10 | 2-5% | <2% |
+
+#### Step 3: Flag Optimization Candidates
+Pages with high impressions but below-average CTR are prime candidates:
+```
+Example:
+Page: /wordpress-speed-guide
+Position: 3
+Impressions: 5,000/month
+CTR: 4.2% (expected 8-12% for position 3)
+→ META OPTIMIZATION NEEDED — potential to double clicks
+```
+
+#### Step 4: Analyze Current Meta
+```
+Use get_content to fetch the current title tag and meta description.
+Evaluate against the rules above.
+Identify specific issues (too long, missing keyword, no CTA, etc.).
+```
+
+### CTR Impact Estimation
+```
+Current: Position 3, 5000 impressions, 4.2% CTR = 210 clicks/month
+After optimization to 8% CTR: 5000 × 0.08 = 400 clicks/month
+Potential gain: +190 clicks/month (+90% improvement)
+```
+
+## A/B Variant Generation
+
+### Process
+
+#### Step 1: Generate Two Variants
+Claude generates two meta description variants using different approaches:
+
+**Variant A: Benefit-focused**
+```
+"Cut your WordPress load time by 50% with these 10 proven optimization
+techniques. Includes caching, image compression, and CDN setup. Free guide."
+```
+
+**Variant B: Problem-focused**
+```
+"Slow WordPress site losing visitors? Fix it with 10 tested speed
+techniques. Average improvement: 50% faster. Step-by-step instructions."
+```
+
+#### Step 2: Score Both Variants
+
+| Criteria | Variant A | Variant B |
+|----------|-----------|-----------|
+| Keyword presence | Yes (1st sentence) | Yes (1st sentence) |
+| Length | 148 chars ✓ | 142 chars ✓ |
+| CTA | "Free guide" | "Step-by-step" |
+| Emotional trigger | Benefit (cut load time) | Pain (losing visitors) |
+| Specificity | 50%, 10 techniques | 50% faster |
+| Readability | Clear | Clear |
+
+#### Step 3: Apply and Monitor
+```
+Apply the highest-scoring variant via update_content.
+Set a review date 2-4 weeks out.
+Compare CTR data in GSC after the review period.
+```
+
+### Title Tag A/B Variants
+Same process for title tags:
+```
+Original: "WordPress Speed Guide"
+Variant A: "WordPress Speed Optimization — 10 Techniques That Work"
+Variant B: "How to Speed Up WordPress by 50% (2026 Guide)"
+```
+
+## Rich Snippet Optimization
+
+### Content-Type Specific Guidance
+
+| Content Type | Rich Snippet Opportunity | Meta Optimization |
+|-------------|------------------------|-------------------|
+| How-to articles | HowTo schema | Include "how to" in title, steps count in meta |
+| FAQ pages | FAQPage schema | Include question in title, "answers" in meta |
+| Product pages | Product schema (rating, price) | Include price/rating in meta |
+| Review posts | Review schema (star rating) | Include rating in title/meta |
+| List posts | ItemList schema | Include count in title ("10 Best...") |
+
+### Meta for Featured Snippets
+To optimize for position zero:
+- Structure content to answer specific questions
+- Use the question as an H2 heading
+- Provide a concise answer in the first paragraph (40-60 words)
+- Follow with detailed explanation
+- Include a summary table or list
+
+## Step-by-Step Workflow
+
+### Step 1: Identify Optimization Targets
+```
+Use gsc_page_performance to find pages with:
+- High impressions (>500/month)
+- Below-average CTR for their position
+- Sort by potential impact (impressions × CTR gap)
+```
+
+### Step 2: Fetch Current Meta Elements
+```
+Use get_content for each target page.
+Extract: title tag, meta description, H1, URL slug.
+```
+
+### Step 3: Analyze and Score Current Meta
+Claude evaluates each element against rules above:
+- Title: length, keyword position, clarity, brand
+- Description: length, keyword, CTA, emotional trigger, specificity
+
+### Step 4: Generate Optimized Variants
+For each page, Claude produces:
+- 2 title tag variants
+- 2 meta description variants
+- Score comparison with current version
+- Estimated CTR impact
+
+### Step 5: Apply Changes
+```
+Use update_content to apply the winning variants.
+Document changes for tracking:
+- Page URL
+- Previous title/meta
+- New title/meta
+- Date changed
+- Baseline CTR from GSC
+```
+
+### Step 6: Monitor Results
+After 2-4 weeks:
+```
+Use gsc_page_performance to pull updated CTR data.
+Compare against baseline.
+Iterate if CTR did not improve.
+```
+
+## Best Practices
+
+- Prioritize high-impression pages first (biggest impact from small CTR gains)
+- Never duplicate meta descriptions across pages
+- Avoid meta descriptions that do not match page content (causes bounce)
+- Include the year in title tags for time-sensitive content (guides, reviews)
+- Use active voice and power verbs in meta descriptions
+- Test one change at a time to isolate impact
+- Review and refresh meta descriptions quarterly
+- Consider search intent when crafting meta — informational vs transactional queries need different approaches
+- Do not force keywords into meta descriptions unnaturally — readability trumps keyword presence

package/skills/wp-content-optimization/references/readability-analysis.md

@@ -0,0 +1,201 @@
+# Readability Analysis
+
+## Overview
+
+Readability analysis measures how easy content is to read and understand. Claude performs Flesch-Kincaid scoring, sentence length analysis, passive voice detection, paragraph assessment, and jargon identification directly on WordPress content — no external readability tools required. The goal is web-optimized content that matches the target audience's reading level.
+
+## Flesch-Kincaid Scoring
+
+### Formula
+```
+Flesch Reading Ease = 206.835 - (1.015 × ASL) - (84.6 × ASW)
+
+Where:
+  ASL = Average Sentence Length (words per sentence)
+  ASW = Average Syllables per Word
+```
+
+### Score Interpretation
+
+| Score | Grade Level | Audience | Action |
+|-------|-------------|----------|--------|
+| 90-100 | 5th grade | Very easy, children | Too simple for most web content |
+| 80-89 | 6th grade | Easy, conversational | Good for broad consumer content |
+| 70-79 | 7th grade | Fairly easy | Good for general web content |
+| 60-69 | 8th-9th grade | Standard | **Target for most WordPress content** |
+| 50-59 | 10th-12th grade | Fairly difficult | Acceptable for professional audience |
+| 30-49 | College | Difficult | Only for specialized/technical content |
+| 0-29 | Graduate | Very difficult | Rewrite for web consumption |
+
+### Target Scores by Content Type
+
+| Content Type | Target Score | Rationale |
+|--------------|-------------|-----------|
+| Blog posts | 60-70 | General audience, scannable |
+| Product descriptions | 65-75 | Clear, benefit-focused |
+| Technical documentation | 45-60 | Professional audience |
+| Landing pages | 70-80 | Must be instantly clear |
+| Email newsletters | 65-75 | Quick reading format |
+
+## Sentence Length Analysis
+
+### Guidelines
+
+| Metric | Target | Flag Threshold |
+|--------|--------|----------------|
+| Average sentence length | 15-20 words | >20 words average |
+| Maximum sentence length | 35 words | >40 words |
+| Short sentence ratio | 20-30% under 10 words | <10% short sentences |
+| Variety | Mix of short, medium, long | All same length |
+
+### Sentence Length Distribution
+Ideal content alternates between sentence lengths for rhythm:
+```
+Short sentence (5-10 words).     ← Punchy, creates emphasis
+Medium sentence (11-20 words).   ← Core information delivery
+Long sentence (21-30 words).     ← Complex ideas, supporting detail
+Short sentence (5-10 words).     ← Reset reader attention
+```
+
+### Fixing Long Sentences
+Strategies for breaking up long sentences:
+1. **Split at conjunctions** — break at "and", "but", "while", "although"
+2. **Remove relative clauses** — move "which" and "that" clauses to new sentences
+3. **Use bullet lists** — convert compound sentences into scannable lists
+4. **Front-load the point** — put the main idea first, details after
+
+### Example
+```
+Before (38 words):
+"WordPress is a content management system that allows users to create websites
+and blogs with themes and plugins, which can be customized to match any brand
+identity and extended with additional functionality."
+
+After (two sentences, 15 + 16 words):
+"WordPress is a content management system for creating websites and blogs.
+Themes and plugins let you customize the design and extend functionality."
+```
+
+## Passive Voice Detection
+
+### What to Flag
+Passive voice constructions where the subject receives the action:
+```
+Passive: "The plugin was installed by the user."
+Active:  "The user installed the plugin."
+```
+
+### Target
+- Maximum 10% of sentences in passive voice
+- 5% or less is ideal for web content
+
+### Common Passive Patterns
+| Passive Pattern | Active Rewrite |
+|----------------|----------------|
+| "was created by" | "[subject] created" |
+| "is recommended" | "we recommend" |
+| "can be configured" | "you can configure" |
+| "has been updated" | "we updated" / "[subject] updated" |
+| "should be installed" | "install" (imperative) |
+
+### When Passive Is Acceptable
+- Scientific or technical writing where the actor is irrelevant
+- When the object is more important than the subject
+- Policy or legal statements
+
+## Paragraph Length Guidelines
+
+| Metric | Target | Flag |
+|--------|--------|------|
+| Sentences per paragraph | 2-4 | >5 sentences |
+| Words per paragraph | 40-80 | >100 words |
+| One-sentence paragraphs | Occasional for emphasis | >3 consecutive |
+| Wall of text | Never | Any paragraph >150 words |
+
+### Web-Specific Rules
+- Break up paragraphs more aggressively than print
+- Use subheadings every 200-300 words
+- Include visual breaks (images, lists, blockquotes) every 300-400 words
+- One idea per paragraph
+
+## Jargon and Complexity Detection
+
+### Flag These Patterns
+1. **Industry jargon** — terms unknown to general audience (e.g., "canonical URL", "transclusion")
+2. **Acronyms without definition** — first use must define the acronym
+3. **Multi-syllable alternatives** — when simpler words exist
+4. **Nominalization** — turning verbs into nouns ("optimization" instead of "optimize")
+5. **Double negatives** — "not uncommon" instead of "common"
+
+### Simplification Table
+
+| Complex | Simple |
+|---------|--------|
+| utilize | use |
+| implement | add / set up |
+| functionality | feature |
+| methodology | method |
+| in order to | to |
+| at this point in time | now |
+| a large number of | many |
+| in the event that | if |
+| prior to | before |
+| subsequent to | after |
+
+## Step-by-Step Workflow
+
+### Step 1: Fetch Content
+```
+Use get_content with the post ID to retrieve full body content.
+Strip HTML tags for text-only analysis.
+```
+
+### Step 2: Compute Metrics
+Claude analyzes the plain text and computes:
+- Total word count
+- Total sentence count
+- Average sentence length (words/sentences)
+- Estimated Flesch-Kincaid score
+- Passive voice percentage
+- Average paragraph length
+- Jargon terms identified
+
+### Step 3: Generate Report
+```
+Readability Report for: "Post Title"
+═══════════════════════════════════
+Flesch-Kincaid Score: 58 (target: 60-70) ⚠ Below target
+Average Sentence Length: 22 words (target: <20) ⚠ Too long
+Passive Voice: 15% (target: <10%) ⚠ Too high
+Avg Paragraph Length: 95 words (target: <80) ⚠ Long paragraphs
+Jargon Terms Found: 3 (canonical, transclusion, REST endpoint)
+
+Top Issues:
+1. 5 sentences over 35 words — break into shorter sentences
+2. 3 paragraphs over 100 words — split with subheadings
+3. "canonical URL" used without definition — add brief explanation
+```
+
+### Step 4: Suggest Improvements
+Claude generates specific rewrite suggestions:
+- Rewrites for the 3 longest sentences
+- Paragraph split points with suggested subheadings
+- Passive-to-active voice conversions
+- Jargon simplifications or definitions to add
+
+### Step 5: Apply Changes (Optional)
+```
+Use update_content to apply approved changes.
+Preserve all HTML structure, links, and media.
+Only modify text content for readability improvements.
+```
+
+## Best Practices
+
+- Always analyze the full post body, not just excerpts
+- Consider the target audience when evaluating scores (technical docs have lower target)
+- Preserve the author's voice — readability improvements should not flatten style
+- Do not oversimplify to the point of losing nuance or accuracy
+- Run readability analysis after SEO optimization to ensure keyword insertion did not harm readability
+- Check readability on both desktop and mobile (shorter paragraphs matter more on mobile)
+- Use transition words (however, therefore, for example) to maintain flow after sentence splitting