claude-plugin-wordpress-manager 2.4.0 → 2.6.0

package/skills/wp-content-optimization/scripts/content_optimization_inspect.mjs

@@ -0,0 +1,237 @@
+/**
+ * content_optimization_inspect.mjs — Detect content optimization readiness.
+ *
+ * Checks WordPress content volume, content age distribution, SEO plugins,
+ * readability plugins, GSC availability, and WooCommerce presence.
+ *
+ * Usage:
+ *   node content_optimization_inspect.mjs [--cwd=/path/to/project]
+ *
+ * Exit codes:
+ *   0 — content optimization readiness found
+ *   1 — no content optimization readiness found
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { argv, stdout, exit } from 'node:process';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function readFileSafe(filePath) {
+  try { return readFileSync(filePath, 'utf-8'); } catch { return null; }
+}
+
+function existsSafe(filePath) {
+  try { return existsSync(filePath); } catch { return false; }
+}
+
+function globDir(dirPath) {
+  try { return readdirSync(dirPath); } catch { return []; }
+}
+
+// ---------------------------------------------------------------------------
+// Detectors
+// ---------------------------------------------------------------------------
+
+function detectContent(cwd) {
+  const indicators = [];
+
+  // Check wp-content directory exists
+  if (!existsSafe(join(cwd, 'wp-content'))) {
+    return { has_content: false, indicators };
+  }
+
+  indicators.push('wp-content directory exists');
+
+  // Check for uploads (indicator of content)
+  const uploads = globDir(join(cwd, 'wp-content', 'uploads'));
+  if (uploads.length > 0) {
+    indicators.push(`wp-content/uploads contains ${uploads.length} entries`);
+  }
+
+  // Check for themes presence
+  const themes = globDir(join(cwd, 'wp-content', 'themes'));
+  if (themes.length > 0) {
+    indicators.push(`${themes.length} theme(s) installed`);
+  }
+
+  const hasContent = uploads.length > 0 || themes.length > 0;
+  return { has_content: hasContent, indicators };
+}
+
+function detectContentAge(cwd) {
+  const indicators = [];
+  const yearsFound = [];
+
+  const uploadsPath = join(cwd, 'wp-content', 'uploads');
+  if (!existsSafe(uploadsPath)) {
+    return { years_found: yearsFound, indicators };
+  }
+
+  const entries = globDir(uploadsPath);
+  const yearPattern = /^(20\d{2})$/;
+
+  for (const entry of entries) {
+    const match = entry.match(yearPattern);
+    if (match) {
+      yearsFound.push(parseInt(match[1], 10));
+      indicators.push(`upload directory found for year ${match[1]}`);
+    }
+  }
+
+  yearsFound.sort();
+
+  if (yearsFound.length > 1) {
+    indicators.push(`content spans ${yearsFound.length} years (${yearsFound[0]}–${yearsFound[yearsFound.length - 1]})`);
+  }
+
+  return { years_found: yearsFound, indicators };
+}
+
+function detectSeoPlugins(cwd) {
+  const indicators = [];
+  const plugins = globDir(join(cwd, 'wp-content', 'plugins'));
+
+  const seoPlugins = [
+    { dir: 'wordpress-seo', name: 'Yoast SEO' },
+    { dir: 'seo-by-rank-math', name: 'RankMath' },
+    { dir: 'all-in-one-seo-pack', name: 'AIOSEO' },
+  ];
+
+  for (const plugin of plugins) {
+    const lower = plugin.toLowerCase();
+    for (const seo of seoPlugins) {
+      if (lower === seo.dir) {
+        indicators.push(`seo_plugin: ${seo.name} (${plugin})`);
+      }
+    }
+  }
+
+  return { found: indicators.length > 0, indicators };
+}
+
+function detectReadability(cwd) {
+  const indicators = [];
+  const plugins = globDir(join(cwd, 'wp-content', 'plugins'));
+
+  // Yoast and RankMath both include readability analysis
+  const readabilityPlugins = [
+    { dir: 'wordpress-seo', name: 'Yoast SEO (readability analysis)' },
+    { dir: 'seo-by-rank-math', name: 'RankMath (readability analysis)' },
+  ];
+
+  for (const plugin of plugins) {
+    const lower = plugin.toLowerCase();
+    for (const rp of readabilityPlugins) {
+      if (lower === rp.dir) {
+        indicators.push(`readability_plugin: ${rp.name}`);
+      }
+    }
+  }
+
+  return { found: indicators.length > 0, indicators };
+}
+
+function detectGsc() {
+  const indicators = [];
+  let configured = false;
+
+  const raw = process.env.WP_SITES_CONFIG;
+  if (!raw) return { configured, indicators };
+
+  let sites;
+  try { sites = JSON.parse(raw); } catch { return { configured, indicators }; }
+  if (!Array.isArray(sites)) return { configured, indicators };
+
+  for (const site of sites) {
+    const label = site.name || site.url || 'unknown';
+    if (site.gsc_service_account_key) {
+      configured = true;
+      indicators.push(`gsc_service_account_key configured for ${label}`);
+    }
+  }
+
+  return { configured, indicators };
+}
+
+function detectWoocommerce(cwd) {
+  const indicators = [];
+  const plugins = globDir(join(cwd, 'wp-content', 'plugins'));
+
+  for (const plugin of plugins) {
+    if (plugin.toLowerCase() === 'woocommerce') {
+      indicators.push(`woocommerce plugin detected (${plugin})`);
+    }
+  }
+
+  return { found: indicators.length > 0, indicators };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const cwdArg = argv.find(a => a.startsWith('--cwd='));
+  const cwd = cwdArg ? resolve(cwdArg.split('=')[1]) : process.cwd();
+
+  const content = detectContent(cwd);
+  const contentAge = detectContentAge(cwd);
+  const seoPlugins = detectSeoPlugins(cwd);
+  const readability = detectReadability(cwd);
+  const gscAvailable = detectGsc();
+  const woocommerce = detectWoocommerce(cwd);
+
+  const found = content.has_content &&
+                (seoPlugins.found || readability.found || gscAvailable.configured);
+
+  const recommendations = [];
+
+  if (content.has_content) {
+    recommendations.push('Content detected — ready for AI-driven optimization analysis');
+  }
+  if (seoPlugins.found) {
+    recommendations.push('SEO plugin detected — headline and meta description optimization can use plugin data');
+  }
+  if (readability.found) {
+    recommendations.push('Readability analysis available — use wp-content-optimization for Flesch-Kincaid scoring');
+  }
+  if (gscAvailable.configured) {
+    recommendations.push('GSC configured — combine search data with content optimization for data-driven improvements');
+  }
+  if (woocommerce.found) {
+    recommendations.push('WooCommerce detected — prioritize optimization of high-revenue content');
+  }
+  if (contentAge.years_found.length > 1) {
+    recommendations.push('Content spans multiple years — run Content Freshness Audit to identify stale content');
+  }
+  if (!content.has_content && !seoPlugins.found && !readability.found && !gscAvailable.configured) {
+    recommendations.push('No content or optimization tools detected — create content first, then use wp-content-optimization');
+  }
+  if (content.has_content && seoPlugins.found && gscAvailable.configured) {
+    recommendations.push('Full optimization stack ready — use wp-content-optimization for comprehensive content triage');
+  }
+
+  const report = {
+    tool: 'content_optimization_inspect',
+    version: '1.0.0',
+    timestamp: new Date().toISOString(),
+    cwd,
+    found,
+    content,
+    content_age: contentAge,
+    seo_plugins: seoPlugins,
+    readability,
+    gsc_available: gscAvailable,
+    woocommerce,
+    recommendations,
+  };
+
+  stdout.write(JSON.stringify(report, null, 2) + '\n');
+  exit(found ? 0 : 1);
+}
+
+main();

package/skills/wp-monitoring/SKILL.md

@@ -129,3 +129,4 @@ See `references/fleet-monitoring.md`
 - **`wp-security`** — hardening procedures triggered by monitoring alerts
 - **`wp-performance`** — optimization actions based on performance trends
 - **`wp-cicd`** — CI/CD quality gates that complement monitoring (pre-deploy checks)
+- **`wp-search-console`** — add GSC search performance checks to periodic SEO monitoring

package/skills/wp-programmatic-seo/SKILL.md

@@ -95,3 +95,5 @@ The script checks headless frontend presence, SEO plugins, content volume, custo
 - `wp-rest-api` — REST API endpoints for content CRUD
 - `wp-content` — content management fundamentals
 - `wp-content-repurposing` — transform existing content into new formats
+- `wp-search-console` — monitor performance of generated pages via GSC keyword tracking and indexing status
+- `wp-content-optimization` — optimize programmatic page templates for headlines, readability, and SEO scoring

package/skills/wp-search-console/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: wp-search-console
+description: This skill should be used when the user asks about "Google Search Console",
+  "GSC", "keyword tracking", "keyword rankings", "search analytics",
+  "indexing status", "URL inspection", "sitemap management",
+  "search performance", "SEO feedback", "content SEO",
+  "competitor gap analysis", "keyword gap", or mentions monitoring
+  WordPress site search performance.
+version: 1.0.0
+---
+
+# WordPress Search Console Skill
+
+## Overview
+
+Google Search Console connects WordPress content to Google Search data via 8 MCP tools. These tools enable keyword tracking, indexing management, sitemap operations, and search performance analysis directly from the WordPress authoring environment. By bridging GSC data with WordPress content, you can identify optimization opportunities, monitor indexing health, and build data-driven content strategies.
+
+## When to Use
+
+- User wants to check how their WordPress pages perform in Google Search
+- User needs to track keyword rankings and position changes over time
+- User asks about indexing status or why a page is not appearing in Google
+- User wants to submit or manage XML sitemaps
+- User needs search analytics data (clicks, impressions, CTR, average position)
+- User asks about content SEO improvements based on search data
+- User wants to identify keyword gaps or content opportunities
+- User needs to inspect a specific URL for crawl and indexing details
+
+## Decision Tree
+
+1. **What aspect of Search Console?**
+   - "setup" / "connect GSC" / "service account" / "verify site" → GSC setup (Section 1)
+   - "keyword tracking" / "rankings" / "position" / "top queries" → Keyword tracking (Section 2)
+   - "indexing" / "URL inspection" / "sitemap" / "crawl" / "not indexed" → Indexing management (Section 3)
+   - "content SEO" / "underperforming pages" / "content refresh" / "optimize title" → Content SEO feedback (Section 4)
+   - "competitor gap" / "keyword gap" / "content opportunities" / "missing keywords" → Competitor gap analysis (Section 5)
+
+2. **Run detection first:**
+   ```bash
+   node skills/wp-search-console/scripts/search_console_inspect.mjs [--cwd=/path/to/project]
+   ```
+   This identifies configured GSC credentials and verified sites.
+
+## Service Overview
+
+| Service | Tools | Auth Type | Use Case |
+|---------|-------|-----------|----------|
+| Google Search Console | 8 tools (`gsc_*`) | Service Account JSON | Search analytics, indexing, sitemaps |
+
+## Sections
+
+### Section 1: GSC Setup
+See `references/gsc-setup.md`
+- Service account creation in Google Cloud Console
+- JSON key file configuration
+- WP_SITES_CONFIG setup with gsc_service_account_key and gsc_site_url
+- Site verification and permissions
+
+### Section 2: Keyword Tracking
+See `references/keyword-tracking.md`
+- Using gsc_search_analytics and gsc_top_queries for keyword monitoring
+- Date range and dimension filters
+- Tracking position changes over time
+- Query-level analysis (clicks, impressions, CTR, average position)
+
+### Section 3: Indexing Management
+See `references/indexing-management.md`
+- Using gsc_inspect_url for indexing status checks
+- Sitemap operations (list, submit, delete)
+- Monitoring crawl coverage
+- Handling indexing issues and bulk URL inspection
+
+### Section 4: Content SEO Feedback
+See `references/content-seo-feedback.md`
+- Connecting search data to WordPress content strategy
+- Identifying underperforming pages with gsc_page_performance
+- Content refresh strategies based on declining metrics
+- Title and meta description optimization from search data
+
+### Section 5: Competitor Gap Analysis
+See `references/competitor-gap-analysis.md`
+- Identifying keyword gaps using search analytics data
+- Analyzing query coverage vs potential queries
+- Finding content opportunities from query data
+- Cross-referencing with WordPress content inventory
+
+## Reference Files
+
+| File | Content |
+|------|---------|
+| `references/gsc-setup.md` | Service account creation, JSON key config, site verification |
+| `references/keyword-tracking.md` | Search analytics queries, position monitoring, dashboards |
+| `references/indexing-management.md` | URL inspection, sitemap management, crawl coverage |
+| `references/content-seo-feedback.md` | Page performance, content refresh, title optimization |
+| `references/competitor-gap-analysis.md` | Keyword gaps, content opportunities, position strategies |
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `gsc_list_sites` | List all verified sites in Google Search Console |
+| `gsc_search_analytics` | Query search analytics data with dimensions and filters |
+| `gsc_inspect_url` | Inspect a URL for indexing status and crawl details |
+| `gsc_list_sitemaps` | List submitted sitemaps and their status |
+| `gsc_submit_sitemap` | Submit a new sitemap URL to GSC |
+| `gsc_delete_sitemap` | Remove a sitemap from GSC |
+| `gsc_top_queries` | Get top search queries with clicks, impressions, CTR, position |
+| `gsc_page_performance` | Get page-level performance data with search metrics |
+
+## Recommended Agent
+
+Use the **`wp-content-strategist`** agent for SEO feedback loops and content optimization workflows that combine Search Console data with WordPress content management.
+
+## Related Skills
+
+- **`wp-programmatic-seo`** — generate SEO-optimized content at scale using search data
+- **`wp-content-attribution`** — track content sources and attribute search traffic
+- **`wp-monitoring`** — monitor site health metrics alongside search performance
+- **`wp-social-email`** — distribute optimized content across social and email channels
+- **`wp-content`** — create and manage WordPress content informed by search analytics
+- **`wp-content-optimization`** — use GSC data as input for AI-driven content optimization and triage

package/skills/wp-search-console/references/competitor-gap-analysis.md

@@ -0,0 +1,226 @@
+# Competitor Gap Analysis
+
+## Overview
+
+Competitor gap analysis uses Google Search Console data to identify keyword opportunities your WordPress site is missing. By analyzing your query coverage, position distribution, and content inventory, you can find topics where you have search visibility but no dedicated content, or where competitors likely rank for queries you do not yet target.
+
+## Identifying Keyword Gaps
+
+### Step 1: Export your full query coverage
+
+```
+Tool: gsc_search_analytics
+Params:
+  site_url: "https://example.com/"
+  start_date: "2026-02-01"
+  end_date: "2026-02-28"
+  dimensions: ["query"]
+  row_limit: 5000
+Returns: Array of all queries with clicks, impressions, ctr, position
+```
+
+This gives you every query Google associates with your site. Sort by impressions to see which topics generate the most search visibility.
+
+### Step 2: Map queries to content
+
+```
+Tool: gsc_search_analytics
+Params:
+  site_url: "https://example.com/"
+  start_date: "2026-02-01"
+  end_date: "2026-02-28"
+  dimensions: ["query", "page"]
+  row_limit: 5000
+```
+
+This maps each query to the page that ranks for it. Look for:
+- **Queries without a dedicated page** — a query matches a generic page rather than a focused article
+- **Multiple queries pointing to one page** — the page may be covering too many topics and could be split
+- **Queries with position > 20** — you appear in results but have no strong content to compete
+
+### Step 3: Identify content gaps
+
+Cross-reference your queries with your WordPress content inventory:
+
+```
+# Get all published content
+Step 1: wp_list_posts status="publish" per_page=100 → Array of posts with titles and URLs
+
+# Get all queries with page mapping
+Step 2: gsc_search_analytics dimensions=["query", "page"] row_limit=5000
+
+# Compare: queries that map to pages not optimized for them = content gaps
+```
+
+## Analyzing Query Coverage
+
+### Position distribution analysis
+
+Categorize your queries by position to understand coverage quality:
+
+```
+Tool: gsc_search_analytics
+Params:
+  site_url: "https://example.com/"
+  start_date: "2026-02-01"
+  end_date: "2026-02-28"
+  dimensions: ["query"]
+  row_limit: 5000
+```
+
+Group results by position ranges:
+
+| Position Range | Category | Strategy |
+|----------------|----------|----------|
+| 1-3 | Dominant | Protect — monitor and update regularly |
+| 4-10 | Competitive | Optimize — content refresh, internal links, backlinks |
+| 11-20 | Striking distance | Target — create supporting content, build topic clusters |
+| 21-50 | Weak presence | Evaluate — is the content worth investing in? |
+| 50+ | Minimal visibility | Decide — create new dedicated content or abandon |
+
+### Topic cluster gaps
+
+Group related queries into topic clusters to find areas where your coverage is incomplete:
+
+1. Export all queries with `gsc_search_analytics`
+2. Group queries by root topic (e.g., "wordpress seo", "wordpress performance", "wordpress security")
+3. Count unique queries per topic and average position per topic
+4. Topics with few queries or high average position are underserved
+
+## Finding Content Opportunities
+
+### High-impression, no-click queries
+
+```
+Tool: gsc_search_analytics
+Params:
+  site_url: "https://example.com/"
+  start_date: "2026-02-01"
+  end_date: "2026-02-28"
+  dimensions: ["query", "page"]
+  row_limit: 1000
+```
+
+Filter for queries where `impressions > 100` and `clicks == 0`. These are searches where Google shows your site but users never click — likely because:
+- Your page does not match the query intent
+- Your title and description are not compelling for that query
+- You rank too low (position > 20) for the query to generate clicks
+
+For each opportunity, decide whether to:
+- **Optimize the existing page** for that query (if the topic is related)
+- **Create a new dedicated page** targeting that query (if the topic is distinct)
+
+### Question-based queries
+
+Filter queries that start with question words (what, how, why, when, where, which, can, does, is):
+
+```
+Tool: gsc_search_analytics
+Params:
+  site_url: "https://example.com/"
+  start_date: "2026-02-01"
+  end_date: "2026-02-28"
+  dimensions: ["query"]
+  dimension_filter_groups:
+    - filters:
+        - dimension: "query"
+          operator: "contains"
+          expression: "how to"
+  row_limit: 200
+```
+
+Question queries map directly to FAQ content, how-to guides, and tutorial posts. If you appear for these queries but don't have dedicated content, create:
+- FAQ sections on existing pages
+- Standalone how-to articles
+- Comprehensive guides that answer multiple related questions
+
+### Long-tail opportunities
+
+Queries with 4+ words are typically long-tail keywords with lower competition:
+
+```
+Tool: gsc_search_analytics
+Params:
+  site_url: "https://example.com/"
+  start_date: "2026-02-01"
+  end_date: "2026-02-28"
+  dimensions: ["query"]
+  row_limit: 2000
+```
+
+Filter for queries containing 4+ words with `impressions > 20`. Long-tail keywords often have:
+- Higher conversion intent
+- Lower competition
+- More specific content requirements
+
+Create focused content addressing the exact long-tail query.
+
+## Position Improvement Strategies
+
+### Strategy 1: Topic clusters
+
+For queries where you rank 11-20, build topic clusters:
+
+1. Identify the core topic from your query data
+2. Create a **pillar page** — comprehensive guide covering the broad topic
+3. Create **cluster pages** — focused articles on subtopics
+4. **Interlink** all cluster pages to the pillar and vice versa
+5. Monitor position changes with `gsc_search_analytics` over 4-8 weeks
+
+### Strategy 2: Content depth expansion
+
+For queries where you rank 4-10 but cannot break into top 3:
+
+1. Analyze the query with `gsc_search_analytics` filtered by the specific query
+2. Fetch the ranking page with `wp_get_post`
+3. Expand the content:
+   - Add 500-1000 words of additional depth
+   - Include data, statistics, or original research
+   - Add images, tables, or diagrams
+   - Add expert quotes or citations
+4. Update via `wp_update_post`
+
+### Strategy 3: Internal link building
+
+Boost underperforming pages with strategic internal links:
+
+1. Identify pages ranking 11-30 for valuable queries
+2. Find high-authority pages on your site (top performers from `gsc_page_performance`)
+3. Add contextual internal links from high-authority pages to underperforming pages
+4. Use the target query as anchor text (naturally, not forced)
+
+## Cross-Referencing with WordPress Content
+
+### Audit workflow
+
+Complete gap analysis workflow combining GSC and WordPress data:
+
+1. **Export all queries**: `gsc_search_analytics` with `dimensions: ["query"]`, `row_limit: 5000`
+2. **Export all pages**: `gsc_page_performance` with `row_limit: 500`
+3. **List WordPress content**: `wp_list_posts` with `status: "publish"`
+4. **Map coverage**: For each WordPress post, check if it has GSC data
+5. **Find orphans**: WordPress posts with no GSC impressions may have indexing or quality issues
+6. **Find gaps**: Queries without a dedicated WordPress post are content opportunities
+
+### Priority scoring
+
+Score content opportunities by potential impact:
+
+| Factor | Weight | Measurement |
+|--------|--------|-------------|
+| Impressions | High | More impressions = more potential traffic |
+| Current position | Medium | Closer to page 1 = easier to improve |
+| CTR gap | Medium | Low CTR vs expected = quick win with title optimization |
+| Competition | Low | Long-tail queries typically have less competition |
+| Business relevance | High | Queries related to products/services have higher value |
+
+## Best Practices
+
+- **Regular cadence**: Run gap analysis monthly to catch new opportunities as query landscape evolves
+- **Focus on intent**: Not all queries are worth targeting; prioritize queries that align with your content goals and business objectives
+- **Quality over quantity**: One comprehensive article targeting a cluster of related queries outperforms five thin articles each targeting a single query
+- **Track outcomes**: After creating content for identified gaps, monitor its performance in GSC after 4-8 weeks
+- **Avoid keyword cannibalization**: Before creating new content, check if an existing page already targets the same query cluster
+- **Use search data directionally**: GSC data shows what Google associates with your site, not what your competitors rank for; use it as a map of your current footprint and expand from there
+- **Combine with external tools**: For true competitive analysis (what competitors rank for that you do not), supplement GSC data with third-party tools like Ahrefs, SEMrush, or Moz
+- **Content calendar integration**: Feed identified opportunities into your WordPress editorial calendar for systematic execution