claude-plugin-wordpress-manager 2.4.0 → 2.6.0

package/skills/wp-content-optimization/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: wp-content-optimization
+description: This skill should be used when the user asks to "optimize content",
+  "improve headlines", "readability analysis", "SEO score", "content scoring",
+  "meta description optimization", "content freshness", "content audit",
+  "content triage", "bulk content optimization", "headline score",
+  "Flesch-Kincaid", "keyword density", or mentions improving existing
+  WordPress content quality and performance.
+version: 1.0.0
+---
+
+# WordPress Content Optimization Skill
+
+## Overview
+
+AI-driven content optimization using Claude's linguistic analysis combined with GSC data (v2.5.0) and WooCommerce attribution data. No external optimization APIs are needed — this skill uses existing WP REST Bridge tools plus Claude's built-in analysis capabilities to perform headline scoring, readability analysis, SEO density checks, meta optimization, content freshness audits, and bulk content triage.
+
+## Philosophy
+
+This is Claude-native. No external optimization APIs like Clearscope, SurferSEO, or MarketMuse are required. Claude itself performs headline analysis, readability scoring, SEO density checks, and content classification by leveraging its linguistic capabilities directly on content fetched through the WP REST Bridge.
+
+## When to Use
+
+- User wants to improve existing content quality
+- User needs headline/title optimization with scoring
+- User asks about readability (Flesch-Kincaid, sentence length)
+- User wants SEO content scoring (keyword density, H-tag coverage)
+- User needs meta description optimization based on CTR data
+- User wants content freshness audit (find stale content)
+- User needs bulk content triage (quick wins vs rewrite vs archive)
+
+## Decision Tree
+
+1. **What type of optimization?**
+   - "optimize headline" / "title score" / "headline analysis" → Headline Analysis (Section 1)
+   - "readability" / "Flesch-Kincaid" / "sentence length" → Readability Analysis (Section 2)
+   - "SEO score" / "keyword density" / "content scoring" → SEO Content Scoring (Section 3)
+   - "meta description" / "title tag" / "CTR optimization" → Meta Description Optimization (Section 4)
+   - "content freshness" / "stale content" / "outdated posts" → Content Freshness Audit (Section 5)
+   - "content triage" / "bulk optimize" / "content audit" → Bulk Content Triage (Section 6 — combines all above)
+
+2. **Run detection first:**
+   ```bash
+   node skills/wp-content-optimization/scripts/content_optimization_inspect.mjs [--cwd=/path/to/project]
+   ```
+   This identifies available content, GSC integration status, and WooCommerce data availability.
+
+## Procedures Overview
+
+| # | Procedure | Input | Output |
+|---|-----------|-------|--------|
+| 1 | Headline Analysis | Title + target keyword | Score 1-10, 3 optimized alternatives |
+| 2 | Readability Analysis | Body content | Flesch-Kincaid score, long sentences, suggestions |
+| 3 | SEO Content Scoring | Body + keyword + GSC data | Keyword density, H2/H3 coverage, internal linking gaps |
+| 4 | Meta Description Optimization | Current meta + GSC CTR data | Optimized meta for CTR, A/B variant |
+| 5 | Content Freshness Audit | Content list + publish date | Stale content identified, update priorities |
+| 6 | Bulk Content Triage | N contents + GSC data | Classified: quick wins, needs rewrite, archive |
+
+## Bulk Content Triage Classification
+
+| Category | Criteria | Action |
+|----------|----------|--------|
+| Quick Wins | High traffic + low CTR, weak headline | Optimize title/meta |
+| Needs Rewrite | >12 months, low readability, keyword off-target | Rewrite content |
+| Performing | High traffic + high CTR | Maintain, refresh date |
+| Archive | Zero traffic >6 months, no keywords | 301 redirect or noindex |
+
+## Sections
+
+### Section 1: Headline Analysis
+See `references/headline-optimization.md`
+- Headline scoring criteria (1-10 scale based on keyword placement, power words, length, clarity)
+- Power word categories (emotional, urgency, curiosity, value)
+- Headline formulas (How-to, List, Question, Comparison)
+- Target keyword placement in headlines
+- A/B title generation workflow
+- Example: fetch via `list_content` → Claude analyzes → generate alternatives → `update_content`
+
+### Section 2: Readability Analysis
+See `references/readability-analysis.md`
+- Flesch-Kincaid scoring (target: 60-70 for general audience)
+- Sentence length analysis (target: <20 words average)
+- Passive voice detection and reduction
+- Paragraph length guidelines
+- Jargon and complexity detection
+- Workflow: fetch content → analyze text → suggest improvements → update
+
+### Section 3: SEO Content Scoring
+See `references/seo-content-scoring.md`
+- Keyword density check (target: 1-2% primary keyword)
+- H2/H3 hierarchy coverage (are subheadings using secondary keywords?)
+- Internal linking analysis (minimum 2-3 internal links per post)
+- External linking (1-2 authoritative sources)
+- Image alt text coverage
+- Combining with `gsc_search_analytics` for keyword data
+
+### Section 4: Meta Description Optimization
+See `references/meta-optimization.md`
+- Title tag best practices (under 60 chars, keyword first)
+- Meta description guidelines (under 160 chars, compelling CTA, keyword inclusion)
+- Using GSC CTR data to identify low-CTR pages for optimization
+- A/B variant generation for testing
+- Rich snippet optimization hints
+
+### Section 5: Content Freshness Audit
+See `references/content-freshness.md`
+- Content decay patterns (traffic drop over time)
+- Freshness signals (published date, modified date, data accuracy)
+- Refresh strategies: date update, data refresh, section expansion, republish
+- Evergreen vs temporal content classification
+- Workflow: `list_content` by date → analyze age → check GSC traffic trends → prioritize
+
+### Section 6: Bulk Content Triage
+Combines all sections above into a single audit workflow:
+1. Fetch all published content via `list_content`
+2. Pull GSC performance data via `gsc_page_performance` and `gsc_top_queries`
+3. Run headline analysis (Section 1) on each title
+4. Run readability analysis (Section 2) on each body
+5. Run SEO content scoring (Section 3) on each post
+6. Cross-reference with GSC CTR data for meta optimization (Section 4)
+7. Check publish dates for freshness audit (Section 5)
+8. Classify each content piece into the triage categories above
+9. Generate prioritized action list
+
+## Reference Files
+
+| File | Content |
+|------|---------|
+| `references/headline-optimization.md` | Headline formulas, power words, scoring criteria |
+| `references/readability-analysis.md` | Flesch-Kincaid, sentence length, passive voice, jargon |
+| `references/seo-content-scoring.md` | Keyword density, H-tag hierarchy, internal link analysis |
+| `references/meta-optimization.md` | Title tag + meta description best practices, CTR optimization |
+| `references/content-freshness.md` | Content decay, refresh strategies, evergreen vs temporal |
+
+## MCP Tools Used
+
+These are existing tools used by the optimization procedures (no new tools introduced):
+
+### WP REST Bridge
+
+| Tool | Usage |
+|------|-------|
+| `list_content` | Fetch published content for analysis |
+| `get_content` | Get full content body for individual post analysis |
+| `update_content` | Apply optimized titles, meta descriptions, content updates |
+
+### Google Search Console (if available)
+
+| Tool | Usage |
+|------|-------|
+| `gsc_page_performance` | Page-level traffic data for triage classification |
+| `gsc_top_queries` | Top queries for keyword density validation |
+| `gsc_search_analytics` | Detailed search metrics for CTR-based meta optimization |
+
+### WooCommerce (if available)
+
+| Tool | Usage |
+|------|-------|
+| `wc_get_orders` | Attribution data linking content to conversions |
+| `wc_list_products` | Product pages for content-commerce optimization |
+
+## Recommended Agent
+
+Use the **`wp-content-strategist`** agent for content optimization workflows that combine Claude's linguistic analysis with search performance data and WordPress content management.
+
+## Related Skills
+
+- **`wp-content`** — create and manage WordPress content
+- **`wp-search-console`** — search performance data for optimization decisions
+- **`wp-content-attribution`** — track content sources and attribute traffic
+- **`wp-programmatic-seo`** — generate SEO-optimized content at scale
+- **`wp-social-email`** — distribute optimized content across channels

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

@@ -0,0 +1,234 @@
+# Content Freshness Audit
+
+## Overview
+
+Content freshness measures how current and accurate published content remains over time. Search engines factor freshness into rankings, and stale content can erode traffic and authority. Claude performs content freshness audits by analyzing publish dates, modification history, traffic trends from GSC, and content accuracy — then classifies content into refresh priorities. This workflow uses `list_content`, `get_content`, and GSC tools.
+
+## Content Decay Patterns
+
+### What Is Content Decay
+Content decay occurs when a page gradually loses organic traffic over time due to:
+- Newer, more comprehensive competitor content
+- Outdated statistics, data, or references
+- Changed search intent for target keywords
+- Algorithm updates favoring fresher content
+- Broken links or outdated external references
+
+### Decay Timeline
+
+| Content Age | Risk Level | Typical Action |
+|-------------|-----------|----------------|
+| 0-6 months | Low | Monitor, no action needed |
+| 6-12 months | Medium | Review for accuracy, consider minor updates |
+| 12-18 months | High | Data refresh, section updates required |
+| 18-24 months | Very High | Major refresh or rewrite |
+| 24+ months | Critical | Full rewrite, republish, or archive |
+
+### Decay Signals
+Indicators that content is decaying:
+1. **Traffic decline** — steady month-over-month drop in organic traffic (via GSC)
+2. **Position drops** — average position worsening for target keywords
+3. **Impression decline** — fewer impressions means less search visibility
+4. **Bounce rate increase** — users leaving quickly (content not meeting expectations)
+5. **Outdated references** — statistics from 2+ years ago, dead links
+
+## Freshness Signals
+
+### What Search Engines Evaluate
+
+| Signal | Description | WordPress Field |
+|--------|-------------|-----------------|
+| Published date | Original publication date | `date` |
+| Modified date | Last content modification | `modified` |
+| Content changes | Actual meaningful edits (not cosmetic) | Content diff |
+| Data currency | Statistics and facts are current | Manual check |
+| Link freshness | External links still active and current | Automated check |
+
+### Meaningful vs Cosmetic Updates
+```
+Meaningful updates (search engines recognize):
+- Adding new sections or paragraphs
+- Updating statistics and data points
+- Adding new examples or case studies
+- Expanding topic coverage
+- Updating recommendations based on new information
+
+Cosmetic updates (do NOT count as fresh):
+- Changing the date without content changes
+- Fixing typos or minor formatting
+- Rearranging existing content
+- Adding images without new text
+- Changing the author
+```
+
+## Refresh Strategies
+
+### Strategy 1: Date and Data Refresh
+**When to use:** Content is fundamentally sound but contains outdated numbers or references.
+```
+Effort: Low (30 min - 1 hour)
+Impact: Medium
+Actions:
+- Update statistics with current data
+- Replace outdated year references
+- Verify all external links still work
+- Update the modified date
+```
+
+### Strategy 2: Section Expansion
+**When to use:** Content covers the topic but competitors have more depth.
+```
+Effort: Medium (1-3 hours)
+Impact: High
+Actions:
+- Add 1-3 new sections addressing gaps
+- Add FAQ section based on current search queries
+- Include updated examples or case studies
+- Add internal links to newer related content
+```
+
+### Strategy 3: Full Rewrite
+**When to use:** Content is outdated, poorly structured, or fundamentally off-target.
+```
+Effort: High (3-6 hours)
+Impact: Very High
+Actions:
+- Rewrite from scratch with current keyword research
+- Maintain the same URL (preserve any existing backlinks)
+- Update all meta elements (title, description)
+- Republish with current date
+- Submit to GSC for re-indexing
+```
+
+### Strategy 4: Republish
+**When to use:** Content is significantly updated and should be treated as new.
+```
+Effort: Medium (after rewrite)
+Impact: High
+Actions:
+- Change publish date to current date
+- Share on social channels as new content
+- Update internal links pointing to this page
+- Submit URL to GSC for re-crawling
+```
+
+### Strategy 5: Archive / Redirect
+**When to use:** Content has no traffic, no keyword value, and no update potential.
+```
+Effort: Low
+Impact: Positive (reduces index bloat)
+Actions:
+- Set up 301 redirect to the most relevant active page
+- Or add noindex meta tag
+- Remove from XML sitemap
+- Remove internal links pointing to this page
+```
+
+## Evergreen vs Temporal Content
+
+### Classification
+
+| Type | Characteristics | Freshness Need | Examples |
+|------|----------------|----------------|----------|
+| Evergreen | Topic stays relevant, answers don't change | Low (annual review) | "How to Install WordPress", "What Is SEO" |
+| Semi-Evergreen | Core topic stable, details change | Medium (6-12 months) | "Best WordPress Plugins 2026", "WordPress Security Guide" |
+| Temporal | Time-bound, loses relevance quickly | High (monthly or event-based) | "WordPress 6.5 New Features", "Black Friday Deals 2026" |
+| News | Immediate relevance, short lifespan | Not refreshable | "WordPress Acquires Company X" |
+
+### Strategy by Content Type
+
+| Type | Refresh Strategy | Frequency |
+|------|-----------------|-----------|
+| Evergreen | Minor data updates, link checks | Every 12 months |
+| Semi-Evergreen | Section expansion, data refresh | Every 6-12 months |
+| Temporal | Full rewrite for new period or archive | When period expires |
+| News | Archive (301 to evergreen resource) | When news cycle ends |
+
+## Content Freshness Audit Workflow
+
+### Step 1: Inventory All Content
+```
+Use list_content to fetch all published posts and pages.
+Collect: post ID, title, URL, publish date, modified date, category.
+Sort by publish date (oldest first).
+```
+
+### Step 2: Calculate Content Age
+```
+For each content piece:
+- Age = current date - publish date
+- Days since last update = current date - modified date
+- Flag: age > 12 months AND no modification in 6+ months
+```
+
+### Step 3: Pull Traffic Trends (GSC)
+```
+Use gsc_page_performance for each page (or top pages by age).
+Compare last 3 months vs previous 3 months:
+- Traffic trend: growing, stable, or declining
+- Position trend: improving, stable, or worsening
+- CTR trend: improving, stable, or declining
+```
+
+### Step 4: Classify Each Content Piece
+```
+For each piece of content, assign a freshness category:
+
+| Category | Criteria |
+|----------|---------|
+| Fresh | <6 months old OR recently updated with growing traffic |
+| Aging | 6-12 months, stable traffic, no recent updates |
+| Stale | 12-18 months, declining traffic, no updates |
+| Decayed | 18+ months, significant traffic loss |
+| Dead | 24+ months, near-zero traffic, no keyword rankings |
+```
+
+### Step 5: Assign Refresh Priority
+```
+Priority 1 (Urgent): Stale content with high historical traffic → quick refresh
+Priority 2 (High):   Aging content in important categories → preventive refresh
+Priority 3 (Medium): Decayed content with some keyword potential → rewrite
+Priority 4 (Low):    Dead content with no recovery potential → archive/redirect
+```
+
+### Step 6: Generate Audit Report
+```
+Content Freshness Audit Report
+══════════════════════════════
+Total Content Pieces: 85
+Fresh (0-6 months):    12 (14%)
+Aging (6-12 months):   23 (27%)
+Stale (12-18 months):  28 (33%)
+Decayed (18-24 months): 15 (18%)
+Dead (24+ months):       7 (8%)
+
+Priority Actions:
+┌─────────┬────────────────────────────────────┬───────────┬──────────────┐
+│ Priority│ Content                            │ Age       │ Action       │
+├─────────┼────────────────────────────────────┼───────────┼──────────────┤
+│ 1       │ "WordPress Speed Guide"            │ 14 months │ Data refresh │
+│ 1       │ "Best WooCommerce Plugins"         │ 16 months │ Rewrite      │
+│ 2       │ "How to Install WordPress"         │ 10 months │ Review       │
+│ 4       │ "WordPress 5.9 Features"           │ 26 months │ Archive      │
+└─────────┴────────────────────────────────────┴───────────┴──────────────┘
+```
+
+### Step 7: Execute Refresh Plan
+For each priority item, apply the appropriate refresh strategy:
+```
+Use get_content to fetch the full content.
+Apply the selected refresh strategy (data refresh, expansion, rewrite).
+Use update_content to publish the updated version.
+Submit refreshed URLs to GSC for re-crawling if significantly changed.
+```
+
+## Best Practices
+
+- Run freshness audits quarterly (every 3 months) for sites with 50+ posts
+- Prioritize high-traffic decaying content over zero-traffic content
+- Always refresh meaningfully — date-only changes do not fool search engines
+- Track content age as a standard metric alongside traffic and rankings
+- Set calendar reminders for semi-evergreen content refresh cycles
+- When refreshing, also update internal links from other posts pointing to the refreshed content
+- Keep a content calendar that includes refresh dates alongside new content publication
+- Consider combining freshness audits with the Bulk Content Triage procedure (SKILL.md Section 6) for comprehensive content management

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