claude-plugin-wordpress-manager 2.4.0 → 2.9.0

package/skills/wp-content-workflows/scripts/workflow_inspect.mjs

@@ -0,0 +1,202 @@
+/**
+ * workflow_inspect.mjs — Detect workflow automation configuration readiness.
+ *
+ * Checks WP_SITES_CONFIG for Slack/SendGrid/Mailchimp credentials.
+ * Scans for automation plugins, custom REST endpoints, WP-Cron config,
+ * and webhook setup.
+ *
+ * Usage:
+ *   node workflow_inspect.mjs [--cwd=/path/to/project]
+ *
+ * Exit codes:
+ *   0 — workflow configuration found
+ *   1 — no workflow configuration 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 detectActionChannelConfig() {
+  const channels = { configured: false, indicators: [], missing: [] };
+  const raw = process.env.WP_SITES_CONFIG;
+  if (!raw) { channels.missing.push('WP_SITES_CONFIG env var not set'); return channels; }
+
+  let sites;
+  try { sites = JSON.parse(raw); } catch { channels.missing.push('WP_SITES_CONFIG is not valid JSON'); return channels; }
+  if (!Array.isArray(sites)) { channels.missing.push('WP_SITES_CONFIG is not an array'); return channels; }
+
+  const keys = ['slack_webhook_url', 'slack_bot_token', 'sendgrid_api_key', 'mailchimp_api_key'];
+
+  for (const site of sites) {
+    const label = site.id || site.url || 'unknown';
+    for (const key of keys) {
+      if (site[key]) {
+        channels.configured = true;
+        channels.indicators.push(`${key} configured for ${label}`);
+      } else {
+        channels.missing.push(`${key} not set for ${label}`);
+      }
+    }
+  }
+  return channels;
+}
+
+function detectAutomationPlugins(cwd) {
+  const result = { found: false, indicators: [], recommendations: [] };
+  const pluginsDir = join(cwd, 'wp-content', 'plugins');
+  const plugins = globDir(pluginsDir);
+
+  const automationPlugins = [
+    'automatewoo',
+    'wp-fusion',
+    'fluent-crm',
+    'suretriggers',
+    'wp-crontrol',
+    'advanced-cron-manager',
+    'advanced-cron-manager-pro',
+  ];
+
+  for (const plugin of automationPlugins) {
+    if (plugins.includes(plugin)) {
+      result.found = true;
+      result.indicators.push(`plugin: ${plugin}`);
+    }
+  }
+
+  if (!result.found) {
+    result.recommendations.push('Install wp-crontrol for cron event management');
+    result.recommendations.push('Consider FluentCRM or AutomateWoo for advanced workflows');
+  }
+  return result;
+}
+
+function detectCustomRestEndpoints(cwd) {
+  const rest = { found: false, indicators: [] };
+
+  // Look for wp-manager workflow namespace in plugin/theme files
+  const muPluginsDir = join(cwd, 'wp-content', 'mu-plugins');
+  const pluginsDir = join(cwd, 'wp-content', 'plugins');
+  const themeDir = join(cwd, 'wp-content', 'themes');
+
+  const searchDirs = [muPluginsDir, pluginsDir, themeDir];
+  const pattern = /register_rest_route\s*\(\s*['"]wp-manager\/v1\/workflows['"]/;
+
+  for (const dir of searchDirs) {
+    const files = globDir(dir);
+    for (const file of files) {
+      const filePath = join(dir, file);
+      if (file.endsWith('.php')) {
+        const content = readFileSafe(filePath);
+        if (content && pattern.test(content)) {
+          rest.found = true;
+          rest.indicators.push(`REST endpoint in ${filePath}`);
+        }
+      }
+    }
+  }
+  return rest;
+}
+
+function detectWpCronConfig(cwd) {
+  const cron = { disabled: false, alternate: false, indicators: [], recommendations: [] };
+
+  const wpConfig = readFileSafe(join(cwd, 'wp-config.php'));
+  if (!wpConfig) {
+    cron.recommendations.push('wp-config.php not found — cannot check cron config');
+    return cron;
+  }
+
+  if (/define\s*\(\s*['"]DISABLE_WP_CRON['"]\s*,\s*true\s*\)/i.test(wpConfig)) {
+    cron.disabled = true;
+    cron.indicators.push('DISABLE_WP_CRON is true — server-side cron expected');
+  }
+  if (/define\s*\(\s*['"]ALTERNATE_WP_CRON['"]\s*,\s*true\s*\)/i.test(wpConfig)) {
+    cron.alternate = true;
+    cron.indicators.push('ALTERNATE_WP_CRON is true — redirect-based cron active');
+  }
+
+  const cronPath = join(cwd, 'wp-cron.php');
+  if (existsSafe(cronPath)) {
+    cron.indicators.push('wp-cron.php found');
+  }
+
+  if (cron.disabled) {
+    cron.recommendations.push('Ensure server cron job calls wp-cron.php for scheduled triggers');
+  }
+  return cron;
+}
+
+function detectWebhookConfig() {
+  const webhooks = { configured: false, indicators: [] };
+  const raw = process.env.WP_SITES_CONFIG;
+  if (!raw) return webhooks;
+
+  let sites;
+  try { sites = JSON.parse(raw); } catch { return webhooks; }
+  if (!Array.isArray(sites)) return webhooks;
+
+  for (const site of sites) {
+    const label = site.id || site.url || 'unknown';
+    if (site.wc_webhook_secret || site.webhook_secret) {
+      webhooks.configured = true;
+      webhooks.indicators.push(`webhook secret configured for ${label}`);
+    }
+    if (site.url) {
+      webhooks.indicators.push(`site URL available for ${label} — wc-webhooks tools can be used`);
+    }
+  }
+  return webhooks;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const cwdArg = argv.find(a => a.startsWith('--cwd='));
+  const cwd = cwdArg ? resolve(cwdArg.split('=')[1]) : process.cwd();
+
+  const channels = detectActionChannelConfig();
+  const plugins = detectAutomationPlugins(cwd);
+  const rest = detectCustomRestEndpoints(cwd);
+  const cron = detectWpCronConfig(cwd);
+  const webhooks = detectWebhookConfig();
+
+  const anyConfigured = channels.configured || plugins.found || rest.found || webhooks.configured || cron.indicators.length > 0;
+
+  const report = {
+    workflow_configured: anyConfigured,
+    action_channels: channels,
+    automation_plugins: plugins,
+    custom_rest_endpoints: rest,
+    wp_cron: cron,
+    webhooks,
+    cwd,
+  };
+
+  stdout.write(JSON.stringify(report, null, 2) + '\n');
+  exit(anyConfigured ? 0 : 1);
+}
+
+main();

package/skills/wp-monitoring/SKILL.md

@@ -129,3 +129,6 @@ 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
+- **`wp-alerting`** — severity-based alert routing (Slack + email) for monitoring findings
+- **`wp-analytics`** — analytics data used in performance dashboards and threshold evaluation

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,122 @@
+---
+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
+- Per correlare keyword GSC con traffico GA4, vedi `wp-analytics`

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