claude-plugin-wordpress-manager 2.4.0 → 2.9.0

package/skills/wp-content-optimization/references/seo-content-scoring.md

@@ -0,0 +1,245 @@
+# SEO Content Scoring
+
+## Overview
+
+SEO content scoring evaluates how well a piece of WordPress content is optimized for search engines. Claude performs keyword density analysis, heading hierarchy assessment, internal and external linking checks, image alt text coverage, and content structure evaluation. When GSC data is available, Claude cross-references actual search queries to validate keyword targeting.
+
+## Keyword Density Analysis
+
+### Target Ranges
+
+| Keyword Type | Target Density | Minimum | Maximum |
+|-------------|---------------|---------|---------|
+| Primary keyword | 1-2% | 0.5% | 3% |
+| Secondary keywords | 0.5-1% each | 0.3% | 1.5% |
+| LSI/related terms | Natural occurrence | — | — |
+
+### Density Calculation
+```
+Keyword Density = (Number of keyword occurrences / Total word count) × 100
+```
+
+### Placement Rules
+1. **Title (H1)** — primary keyword must appear (preferably front-loaded)
+2. **First paragraph** — primary keyword within first 100 words
+3. **Subheadings** — primary or secondary keyword in at least 1 H2
+4. **Body distribution** — keyword spread throughout, not clustered
+5. **Last paragraph** — primary keyword in conclusion
+6. **URL slug** — primary keyword in the URL
+
+### Keyword Stuffing Detection
+Flag when:
+- Primary keyword density exceeds 3%
+- Same keyword appears in consecutive sentences
+- Keyword is forced into unnatural phrasing
+- Multiple exact-match keyword repetitions in one paragraph
+
+### Example Analysis
+```
+Post: "WordPress Speed Optimization Guide" (1500 words)
+Primary keyword: "wordpress speed optimization"
+
+Occurrences: 18 times
+Density: 18/1500 × 100 = 1.2% ✓ Within target
+
+Distribution:
+- Title: ✓ Present
+- First paragraph: ✓ Present (word 12)
+- H2 headings: ✓ 1 of 4 H2s contains keyword
+- Last paragraph: ✓ Present
+- URL: ✓ /wordpress-speed-optimization-guide
+```
+
+## H2/H3 Hierarchy Coverage
+
+### Structure Requirements
+
+| Element | Requirement | Check |
+|---------|------------|-------|
+| H1 | Exactly 1 per page, contains primary keyword | Required |
+| H2 | 2-6 per post, secondary keywords in 50%+ | Required |
+| H3 | As needed under H2, long-tail keywords | Recommended |
+| H4+ | Rare, deep detail only | Optional |
+| Skip levels | Never (H1 → H3 without H2) | Flag as error |
+
+### Heading Optimization Checklist
+- [ ] One H1 only, matching the post title
+- [ ] H2s outline the main sections (scannable table of contents)
+- [ ] At least one H2 contains the primary keyword
+- [ ] H3s provide detail under their parent H2
+- [ ] No heading level is skipped
+- [ ] Headings are descriptive (not generic like "More Info")
+- [ ] Secondary keywords distributed across H2/H3 headings
+
+### Example Heading Audit
+```
+H1: WordPress Speed Optimization: Complete Guide          ✓ Primary keyword
+  H2: Why WordPress Speed Matters                         ✓ Descriptive
+    H3: Impact on SEO Rankings                            ✓ Secondary keyword
+    H3: Impact on User Experience                         ✓ Related term
+  H2: How to Measure WordPress Speed                      ✓ Secondary keyword
+  H2: 10 WordPress Speed Optimization Techniques          ✓ Primary keyword
+    H3: Enable Caching                                    ✓ Specific
+    H3: Optimize Images                                   ✓ Specific
+    H3: Minimize CSS and JavaScript                       ✓ Specific
+  H2: Conclusion                                          ⚠ Generic, add keyword
+```
+
+## Internal Linking Analysis
+
+### Minimum Standards
+
+| Content Length | Internal Links | Rationale |
+|---------------|---------------|-----------|
+| < 500 words | 1-2 links | Short content, few linking opportunities |
+| 500-1000 words | 2-3 links | Standard blog post |
+| 1000-2000 words | 3-5 links | In-depth article |
+| 2000+ words | 5-8 links | Pillar content, extensive topic |
+
+### What to Check
+1. **Link count** — meets minimum for content length
+2. **Anchor text** — descriptive, keyword-rich (not "click here")
+3. **Link relevance** — linked pages are topically related
+4. **Link distribution** — links spread throughout content, not clustered
+5. **Orphan detection** — identify posts with zero inbound internal links
+6. **Reciprocal links** — pillar pages link to cluster posts and vice versa
+
+### Link Opportunity Detection
+Claude identifies linking opportunities by:
+- Finding mentions of topics that have dedicated pages on the site
+- Detecting keyword phrases that match other post titles
+- Identifying related content that could provide context
+- Suggesting links to pillar pages from cluster content
+
+## External Linking
+
+### Guidelines
+
+| Metric | Target |
+|--------|--------|
+| External links per post | 1-2 minimum |
+| Link targets | Authoritative, relevant sources (.gov, .edu, industry leaders) |
+| Link freshness | Source content should be current (not outdated) |
+| Nofollow | Use for sponsored or untrusted links |
+| Open in new tab | Yes for external links (target="_blank") |
+
+### What to Avoid
+- Linking to direct competitors' commercial pages
+- Linking to low-authority or spammy sites
+- Excessive external links (>5 per 1000 words)
+- Broken external links (check periodically)
+
+## Image Alt Text Coverage
+
+### Requirements
+| Check | Standard |
+|-------|----------|
+| All images have alt text | 100% coverage required |
+| Alt text includes keyword | At least 1 image per post |
+| Alt text is descriptive | Describes the image content |
+| Alt text length | 5-15 words |
+| Decorative images | Empty alt="" (not missing alt) |
+
+### Example
+```
+Good: alt="WordPress performance optimization dashboard showing page load times"
+Bad:  alt="image1" or alt="" (on informational image) or alt missing
+```
+
+## Combining with GSC Data
+
+When Google Search Console is available, enrich the SEO scoring with real search data:
+
+### Step 1: Fetch Search Queries for the Page
+```
+Use gsc_search_analytics with the page URL to get actual queries driving traffic.
+```
+
+### Step 2: Compare Target vs Actual Keywords
+```
+Target keyword: "wordpress speed optimization"
+Actual top queries from GSC:
+  1. "wordpress speed" (pos 8, 500 impressions)
+  2. "wordpress performance" (pos 12, 300 impressions)
+  3. "how to speed up wordpress" (pos 15, 200 impressions)
+
+Analysis: Content ranks for related terms but not the exact target.
+Action: Strengthen primary keyword presence, add "how to speed up wordpress" as H2.
+```
+
+### Step 3: Identify Keyword Gaps
+- Queries with high impressions but low CTR → meta description issue
+- Queries with high position (>10) → content depth issue
+- Queries the page ranks for that are not in the content → add sections
+
+## SEO Content Score Card
+
+### Scoring Template
+```
+SEO Content Score for: "Post Title"
+═════════════════════════════════════
+Keyword Density:      1.2%    ✓ (target: 1-2%)
+Keyword in H1:        Yes     ✓
+Keyword in First 100: Yes     ✓
+Keyword in URL:       Yes     ✓
+
+H2 Count:             4       ✓ (target: 2-6)
+H2 with Keywords:     2/4     ✓ (target: 50%+)
+H3 Count:             6       ✓
+Heading Hierarchy:    Valid   ✓ (no skipped levels)
+
+Internal Links:       2       ⚠ (target: 3-5 for 1200 words)
+External Links:       1       ✓ (target: 1-2)
+Anchor Text Quality:  Good    ✓
+
+Image Alt Coverage:   3/4     ⚠ (1 image missing alt text)
+Keyword in Alt:       1/4     ✓
+
+Overall Score:        7.5/10
+Priority Fixes:
+1. Add 1-2 more internal links to related content
+2. Add alt text to image in section 3
+```
+
+## Step-by-Step Workflow
+
+### Step 1: Fetch Content
+```
+Use get_content to retrieve the full post HTML.
+Parse headings, links, images, and body text.
+```
+
+### Step 2: Identify Target Keyword
+Either provided by user or extracted from:
+- Post title analysis
+- GSC top query for the URL
+- Content theme analysis
+
+### Step 3: Run All Checks
+Claude analyzes in sequence:
+1. Keyword density and placement
+2. Heading hierarchy and keyword coverage
+3. Internal and external link audit
+4. Image alt text coverage
+5. GSC data cross-reference (if available)
+
+### Step 4: Generate Score Card
+Produce the formatted score card with pass/fail for each criterion.
+
+### Step 5: Prioritize Fixes
+Rank issues by impact:
+1. Missing keyword in title/H1 (highest impact)
+2. Keyword density out of range
+3. No internal links
+4. Missing alt text
+5. Heading hierarchy issues
+6. External link additions
+
+## Best Practices
+
+- Run SEO scoring before publishing (pre-publish checklist)
+- Re-score after content updates to ensure changes did not break optimization
+- Use GSC data to validate keyword targeting against real search behavior
+- Do not sacrifice readability for SEO score — readability comes first
+- Update scoring analysis quarterly as search patterns evolve
+- Track score changes over time to measure optimization impact

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-content-workflows/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: wp-content-workflows
+description: This skill should be used when the user asks about "workflow automation",
+  "triggers", "scheduled tasks", "WP-Cron", "content publishing triggers",
+  "hook-based actions", "post status transitions", "automated notifications",
+  "workflow triggers", "event-driven actions", "content lifecycle hooks",
+  "multi-channel actions", "trigger management", or mentions setting up
+  automated workflows that fire on WordPress events or schedules.
+version: 1.0.0
+tags: [workflows, triggers, cron, automation, hooks, scheduling]
+---
+
+# WordPress Content Workflows Skill
+
+## Overview
+
+Event-driven workflow automation system for WordPress. Combines WP-Cron scheduling, content lifecycle hooks, and WordPress action/filter hooks to trigger multi-channel actions (Slack, email, webhook). Provides trigger creation, management, testing (dry-run), and audit logging. This skill connects WordPress events to notification and action channels, enabling automated responses to content changes, user actions, and scheduled tasks.
+
+## When to Use
+
+- User wants to create automated triggers for WordPress events
+- User needs scheduled tasks (cron-based publishing, periodic reports)
+- User asks about post status transitions (draft to published, trash, etc.)
+- User wants to hook into WordPress actions (user_register, comment_post, etc.)
+- User needs multi-channel action routing (Slack + email + webhook on same event)
+- User asks about trigger management (list, test, enable/disable, delete)
+- User wants to set up WooCommerce order-based workflows
+- User needs to audit or troubleshoot existing workflow triggers
+
+## Decision Tree
+
+1. **What type of trigger?**
+   - "cron" / "scheduled" / "periodic" → Schedule-Based Triggers (Procedure 1)
+   - "on publish" / "post status" / "content change" → Content Lifecycle Hooks (Procedure 2)
+   - "on login" / "user register" / "comment" / "plugin" → WP Action/Filter Hooks (Procedure 3)
+   - "notify Slack and email" / "multi-channel" → Multi-Channel Action Configuration (Procedure 4)
+   - "list triggers" / "test" / "disable" / "delete" → Trigger Management (Procedure 5)
+
+2. **Run detection first:**
+   ```bash
+   node skills/wp-content-workflows/scripts/workflow_inspect.mjs [--cwd=/path/to/project]
+   ```
+   This identifies configured action channels, automation plugins, WP-Cron status, and webhook setup.
+
+## Procedures
+
+### Procedure 1: Schedule-Based Triggers
+
+See `references/schedule-triggers.md`
+- Configure WP-Cron intervals (hourly, twicedaily, daily, weekly, custom)
+- Set up scheduled content publishing triggers
+- Create recurring health check and report triggers
+- External cron setup (server cron vs WP-Cron)
+- Test scheduled trigger with `wf_create_trigger` using cron schedule type
+
+### Procedure 2: Content Lifecycle Hooks
+
+See `references/content-lifecycle-hooks.md`
+- Hook into post status transitions (draft→published, published→trash)
+- Support custom post types (products, portfolios, events)
+- Monitor taxonomy and term changes
+- Track media upload events
+- Create trigger with `wf_create_trigger` using content lifecycle event type
+
+### Procedure 3: WP Action/Filter Hooks
+
+See `references/wp-action-hooks.md`
+- Hook into core WordPress actions (user_register, wp_login, comment_post)
+- WooCommerce hooks (woocommerce_new_order, woocommerce_order_status_changed)
+- Plugin activation/deactivation hooks
+- Filter hooks for content transformation workflows
+- Create trigger with `wf_create_trigger` using action hook event type
+
+### Procedure 4: Multi-Channel Action Configuration
+
+See `references/multi-channel-actions.md`
+- Map triggers to one or more action channels (Slack, email, webhook)
+- Configure template variables ({{post_title}}, {{user_name}}, {{order_total}})
+- Channel-specific formatting (Block Kit for Slack, HTML for email, JSON for webhook)
+- Rate limiting per channel to prevent flooding
+- Update trigger actions with `wf_update_trigger`
+
+### Procedure 5: Trigger Management
+
+See `references/trigger-management.md`
+- List and filter triggers with `wf_list_triggers`
+- Activate/deactivate triggers without deleting (via `wf_update_trigger`)
+- Test triggers in dry-run mode
+- Review trigger audit log
+- Bulk operations (enable/disable all, export/import)
+- Delete stale triggers with `wf_delete_trigger`
+
+## MCP Tools Reference
+
+| Tool | Description |
+|------|-------------|
+| `wf_list_triggers` | List all workflow triggers with optional status/type filters |
+| `wf_create_trigger` | Create a new workflow trigger (cron, lifecycle, action hook) |
+| `wf_update_trigger` | Update trigger config, actions, or status (active/inactive) |
+| `wf_delete_trigger` | Delete a workflow trigger (with safety confirmation) |
+
+## Reference Files
+
+| File | Content |
+|------|---------|
+| `references/schedule-triggers.md` | WP-Cron patterns, custom intervals, external cron setup |
+| `references/content-lifecycle-hooks.md` | Post status transitions, CPT support, taxonomy changes, media events |
+| `references/wp-action-hooks.md` | Core WP actions, WooCommerce hooks, plugin hooks, filter hooks |
+| `references/multi-channel-actions.md` | Channel config, template variables, formatting, rate limiting |
+| `references/trigger-management.md` | Listing, activate/deactivate, dry-run testing, audit log, bulk ops |
+
+## Recommended Agent
+
+Use the **`wp-site-manager`** for automated workflow orchestration that combines trigger creation, multi-channel action routing, and lifecycle management.
+
+## Related Skills
+
+- **`wp-alerting`** — shares Slack and SendGrid channels for notification delivery
+- **`wp-monitoring`** — source of health/performance data that may trigger workflows
+- **`wp-webhooks`** — outbound/inbound webhook infrastructure for webhook action channel
+- **`wp-social-email`** — shares SendGrid and Mailchimp config for email actions
+
+## Cross-references
+
+- Workflow triggers pair with `wp-alerting` for severity-based notification routing
+- Scheduled triggers depend on WP-Cron config detectable via `wp-monitoring`
+- Webhook actions use `wp-webhooks` infrastructure for outbound delivery
+- Email actions share SendGrid/Mailchimp config with `wp-social-email`
+- WooCommerce hooks connect to `wp-woocommerce` for order-based workflows
+
+## Troubleshooting
+
+| Issue | Cause | Resolution |
+|-------|-------|------------|
+| Cron trigger not firing | DISABLE_WP_CRON is true and no server cron configured | Set up server cron job: `*/5 * * * * wget -qO- https://example.com/wp-cron.php` |
+| Content hook missed | Post updated via direct DB query (bypasses hooks) | Ensure content changes go through `wp_update_post()` or REST API |
+| Slack action fails | slack_webhook_url or slack_bot_token not configured | Add Slack credentials to WP_SITES_CONFIG |
+| Email action 403 | SendGrid API key lacks Mail Send permission | Regenerate key with "Mail Send" access in SendGrid dashboard |
+| Duplicate triggers firing | Multiple hooks registered for same event | Review triggers with `wf_list_triggers` and deduplicate |
+| Trigger test fails | Action channel unreachable or credentials expired | Run `workflow_inspect.mjs` to verify channel configuration |
+| WooCommerce hooks silent | WooCommerce not active or hooks not registered | Verify WooCommerce is active; hooks fire only after `woocommerce_init` |
+| Detection script exit 1 | No workflow config found | Add action channel credentials to WP_SITES_CONFIG and install wp-crontrol |