claude-plugin-wordpress-manager 2.4.0 → 2.9.0

package/skills/wp-search-console/references/content-seo-feedback.md

@@ -0,0 +1,181 @@
+# Content SEO Feedback
+
+## Overview
+
+Content SEO feedback connects Google Search Console performance data to WordPress content strategy. By analyzing page-level metrics (clicks, impressions, CTR, position), you can identify underperforming content, discover optimization opportunities, and make data-driven decisions about content refreshes, title rewrites, and new content creation.
+
+## Identifying Underperforming Pages
+
+### Get page-level performance data
+
+```
+Tool: gsc_page_performance
+Params:
+  site_url: "https://example.com/"
+  start_date: "2026-02-01"
+  end_date: "2026-02-28"
+  row_limit: 200
+Returns: Array of pages with clicks, impressions, ctr, position
+```
+
+### Detect declining pages
+
+Compare two periods to find pages with declining performance:
+
+```
+# Previous period
+Tool: gsc_page_performance
+Params:
+  site_url: "https://example.com/"
+  start_date: "2026-01-01"
+  end_date: "2026-01-31"
+  row_limit: 200
+
+# Current period
+Tool: gsc_page_performance
+Params:
+  site_url: "https://example.com/"
+  start_date: "2026-02-01"
+  end_date: "2026-02-28"
+  row_limit: 200
+```
+
+Compare results to identify:
+- **Click decline > 20%** — high priority for content refresh
+- **Impression decline > 30%** — content may be losing relevance or competitors have overtaken
+- **Position increase > 3 positions** (lower is better) — content is dropping in rankings
+
+### Categorize pages by performance
+
+| Category | Criteria | Action |
+|----------|----------|--------|
+| High performers | Top 10% by clicks | Protect and expand — add internal links, update regularly |
+| Declining stars | Previously top, now dropping | Content refresh — update data, add sections, improve media |
+| Hidden gems | High impressions, low CTR | Title/meta optimization — rewrite to improve click-through |
+| Dead weight | Low impressions, low clicks | Evaluate for removal, consolidation, or major rewrite |
+| Rising pages | Increasing impressions and clicks | Accelerate — build more internal links, add supporting content |
+
+## Content Refresh Strategies
+
+### Strategy 1: Refresh based on declining clicks
+
+1. **Identify declining pages** using period comparison (see above)
+2. **Fetch the WordPress content** using `wp_get_post` with the page URL
+3. **Analyze queries** driving traffic to the page using `gsc_search_analytics` with `dimensions: ["query"]` filtered by the page URL
+4. **Update the content** to better address the top queries:
+   - Add missing subtopics that queries suggest users are looking for
+   - Update outdated statistics, dates, and references
+   - Expand thin sections with more depth
+   - Add FAQ sections based on question-type queries
+
+```
+# Find queries for a specific declining page
+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: "page"
+          operator: "equals"
+          expression: "https://example.com/blog/wordpress-performance/"
+  row_limit: 50
+```
+
+### Strategy 2: New content from high-impression queries
+
+Queries with high impressions but low or zero clicks on your pages represent untapped opportunities:
+
+```
+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: 500
+```
+
+Filter for queries where:
+- `impressions > 200` and `clicks < 5` — your page appears but users do not click
+- `position > 10` — you rank on page 2+ and need a dedicated, optimized page
+
+These queries can inform new blog post topics or dedicated landing pages.
+
+### Strategy 3: Content consolidation
+
+Multiple pages ranking for the same query cannibalize each other:
+
+```
+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
+```
+
+Look for queries that appear with 2+ different pages. When multiple pages compete:
+1. Choose the strongest page (most clicks/best position)
+2. Merge content from the weaker page into the stronger one
+3. Redirect the weaker URL to the stronger page
+4. Update internal links to point to the consolidated page
+
+## Title and Meta Description Optimization
+
+### Find CTR optimization opportunities
+
+```
+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: 200
+```
+
+Target pages where:
+- `position < 5` and `ctr < 0.05` — ranking well but not getting clicks (expected CTR for top 5 is 5-15%)
+- `position < 3` and `ctr < 0.10` — top 3 positions should have 10%+ CTR
+
+### Title tag optimization guidelines
+
+Based on search data patterns:
+- **Include the primary query** in the title — queries that appear verbatim in titles get higher CTR
+- **Front-load keywords** — the first 60 characters are visible in SERPs
+- **Add power words** — "Guide", "2026", "Complete", "Best" boost CTR by 5-15%
+- **Use numbers** — "10 Tips", "5 Steps" increase CTR by 10-20% vs generic titles
+- **Match intent** — if queries are questions, use question format in title
+
+### Meta description optimization
+
+- **Include target query** — Google bolds matching terms in descriptions
+- **Add a CTA** — "Learn more", "Get started", "Read the full guide"
+- **Stay under 155 characters** — longer descriptions get truncated
+- **Differentiate from competitors** — include unique value propositions
+
+## WordPress Integration Workflow
+
+Complete content optimization loop using GSC data and WordPress tools:
+
+1. **Pull page performance**: `gsc_page_performance` for all pages
+2. **Identify targets**: Filter for declining or underperforming pages
+3. **Get query context**: `gsc_search_analytics` filtered by target page URL
+4. **Fetch WordPress content**: `wp_get_post` to get current content
+5. **Update content**: `wp_update_post` with improved title, content, and meta
+6. **Monitor results**: Re-check `gsc_page_performance` after 2-4 weeks
+
+## Best Practices
+
+- **Refresh cadence**: Review page performance monthly; refresh declining content quarterly
+- **Data threshold**: Only act on pages with 100+ impressions — below that, data is statistically unreliable
+- **Patience after changes**: Wait 2-4 weeks after content changes before measuring impact; Google needs time to re-crawl and re-evaluate
+- **Track changes**: Note the date and nature of each content update so you can correlate with performance changes
+- **Prioritize by impact**: Focus on pages with the highest impression volume first — small CTR improvements on high-impression pages yield more clicks than large improvements on low-impression pages
+- **Seasonal awareness**: Some traffic drops are seasonal, not quality-related; compare year-over-year when possible
+- **Avoid over-optimization**: Do not stuff keywords into titles or content; natural language performs better in modern search
+- **Internal linking**: After refreshing content, add internal links from other relevant pages to boost crawl priority

package/skills/wp-search-console/references/gsc-setup.md

@@ -0,0 +1,110 @@
+# GSC Setup
+
+## Overview
+
+Google Search Console integration requires a Google Cloud service account with Search Console API access. The service account's JSON key file is configured in `WP_SITES_CONFIG`, enabling all 8 GSC MCP tools to authenticate and query search data for your WordPress site.
+
+## Setup
+
+### Step 1: Create a Google Cloud Project
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select an existing one
+3. Enable the **Google Search Console API** (also called "Search Console API" or "Webmasters API") under APIs & Services → Library
+
+### Step 2: Create a Service Account
+
+1. Navigate to IAM & Admin → Service Accounts
+2. Click **Create Service Account**
+3. Name it (e.g., `wp-search-console`) and add a description
+4. No additional roles are needed at the project level
+5. Click **Done**
+
+### Step 3: Generate JSON Key File
+
+1. Click on the newly created service account
+2. Go to the **Keys** tab
+3. Click **Add Key** → **Create new key** → **JSON**
+4. Download the JSON key file and store it securely
+
+The JSON key file contains:
+
+```json
+{
+  "type": "service_account",
+  "project_id": "your-project-id",
+  "private_key_id": "key-id",
+  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
+  "client_email": "wp-search-console@your-project.iam.gserviceaccount.com",
+  "client_id": "123456789",
+  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+  "token_uri": "https://oauth2.googleapis.com/token"
+}
+```
+
+### Step 4: Grant Search Console Access
+
+1. Go to [Google Search Console](https://search.google.com/search-console)
+2. Select your property (site)
+3. Navigate to **Settings** → **Users and permissions**
+4. Click **Add user**
+5. Enter the service account email (e.g., `wp-search-console@your-project.iam.gserviceaccount.com`)
+6. Set permission to **Full** (for read access and sitemap management) or **Restricted** (read-only)
+
+### Step 5: Configure WP_SITES_CONFIG
+
+Add GSC credentials to your site configuration:
+
+```json
+{
+  "sites": [{
+    "name": "my-site",
+    "url": "https://example.com",
+    "gsc": {
+      "gsc_service_account_key": "/path/to/service-account-key.json",
+      "gsc_site_url": "https://example.com/"
+    }
+  }]
+}
+```
+
+**Important notes on `gsc_site_url`:**
+- Use the exact property URL as it appears in Search Console
+- For domain properties, use `sc-domain:example.com`
+- For URL-prefix properties, use the full URL with trailing slash: `https://example.com/`
+- The value must match exactly — a mismatch will result in 403 errors
+
+## Verification
+
+After configuration, verify the setup works:
+
+```
+Tool: gsc_list_sites
+Returns: Array of verified sites with siteUrl, permissionLevel
+```
+
+You should see your site listed with `permissionLevel` of `siteOwner` or `siteFullUser`.
+
+## Permissions and Scopes
+
+The service account requires the following OAuth scope:
+
+- `https://www.googleapis.com/auth/webmasters.readonly` — for read-only access (search analytics, URL inspection, sitemap listing)
+- `https://www.googleapis.com/auth/webmasters` — for full access (includes sitemap submission and deletion)
+
+The MCP tools automatically request the appropriate scope based on the operation.
+
+## Troubleshooting
+
+- **403 Forbidden**: The service account email has not been added to Search Console, or `gsc_site_url` does not match the property URL
+- **404 Not Found**: The site URL format is incorrect (missing trailing slash or wrong protocol)
+- **Authentication errors**: The JSON key file path is invalid or the file is malformed
+- **No data returned**: The site may be newly verified; Search Console data takes 24-48 hours to populate
+
+## Best Practices
+
+- **Key file security**: Store the JSON key file outside the project directory; never commit it to version control
+- **Least privilege**: Use **Restricted** permission if you only need read access (search analytics, URL inspection)
+- **Separate accounts**: Use a dedicated service account per project to isolate access
+- **Key rotation**: Rotate service account keys periodically (every 90 days recommended)
+- **Domain property**: Prefer domain-level properties (`sc-domain:example.com`) over URL-prefix properties for complete data coverage

package/skills/wp-search-console/references/indexing-management.md

@@ -0,0 +1,182 @@
+# Indexing Management
+
+## Overview
+
+Indexing management ensures that Google discovers, crawls, and indexes your WordPress pages correctly. The GSC MCP tools provide URL inspection for individual pages and sitemap management for bulk discovery. Together, these tools help you monitor crawl coverage, diagnose indexing issues, and control which pages appear in search results.
+
+## URL Inspection
+
+### Inspect a single URL
+
+```
+Tool: gsc_inspect_url
+Params:
+  site_url: "https://example.com/"
+  inspection_url: "https://example.com/blog/wordpress-seo-guide/"
+Returns:
+  indexStatusResult:
+    verdict: "PASS"                    # PASS | NEUTRAL | FAIL
+    coverageState: "Submitted and indexed"
+    robotsTxtState: "ALLOWED"
+    indexingState: "INDEXING_ALLOWED"
+    lastCrawlTime: "2026-02-25T10:30:00Z"
+    pageFetchState: "SUCCESSFUL"
+    crawledAs: "MOBILE"
+  mobileUsabilityResult:
+    verdict: "PASS"
+  richResultsResult:
+    detectedItems: [...]
+```
+
+### Understanding inspection results
+
+Key fields in the response:
+
+| Field | Values | Meaning |
+|-------|--------|---------|
+| `verdict` | PASS / NEUTRAL / FAIL | Overall indexing status |
+| `coverageState` | Various | Detailed coverage status |
+| `robotsTxtState` | ALLOWED / DISALLOWED | Whether robots.txt blocks the URL |
+| `indexingState` | INDEXING_ALLOWED / INDEXING_NOT_ALLOWED | Whether meta robots/noindex blocks indexing |
+| `pageFetchState` | SUCCESSFUL / SOFT_404 / NOT_FOUND / REDIRECT | Crawl outcome |
+| `crawledAs` | MOBILE / DESKTOP | Which crawler accessed the page |
+
+### Common coverage states
+
+- **Submitted and indexed** — page is in the index and appearing in search results
+- **Crawled - currently not indexed** — Google crawled it but chose not to index (quality or duplicate concern)
+- **Discovered - currently not indexed** — Google knows about it but has not crawled it yet
+- **Excluded by 'noindex' tag** — the page has a noindex directive
+- **Blocked by robots.txt** — robots.txt prevents crawling
+- **Page with redirect** — the URL redirects to another page
+- **Soft 404** — the page returns 200 but Google treats it as a 404
+
+## Sitemap Management
+
+### List sitemaps
+
+```
+Tool: gsc_list_sitemaps
+Params:
+  site_url: "https://example.com/"
+Returns: Array of sitemaps with:
+  path: "https://example.com/sitemap_index.xml"
+  lastSubmitted: "2026-02-20T08:00:00Z"
+  isPending: false
+  isSitemapsIndex: true
+  lastDownloaded: "2026-02-25T06:00:00Z"
+  warnings: 0
+  errors: 0
+  contents:
+    - type: "web"
+      submitted: 150
+      indexed: 142
+```
+
+### Submit a sitemap
+
+```
+Tool: gsc_submit_sitemap
+Params:
+  site_url: "https://example.com/"
+  sitemap_url: "https://example.com/sitemap_index.xml"
+```
+
+Submit after:
+- Initial site setup
+- Adding a new sitemap (e.g., a video sitemap or news sitemap)
+- Changing sitemap URL structure
+- Major content additions (100+ new pages)
+
+### Delete a sitemap
+
+```
+Tool: gsc_delete_sitemap
+Params:
+  site_url: "https://example.com/"
+  sitemap_url: "https://example.com/old-sitemap.xml"
+```
+
+Delete when:
+- A sitemap URL has changed (submit the new one, delete the old)
+- A sitemap contains only 404/removed pages
+- Consolidating multiple sitemaps into one
+
+## Monitoring Crawl Coverage
+
+### Bulk URL inspection workflow
+
+For auditing multiple pages, iterate through URLs from your WordPress site:
+
+1. **Get WordPress pages** using `wp_list_posts` with `status: "publish"`
+2. **Inspect each URL** using `gsc_inspect_url` for each published page
+3. **Categorize results** by `coverageState`:
+   - Indexed: `verdict === "PASS"`
+   - Not indexed: `verdict === "FAIL"` or `verdict === "NEUTRAL"`
+4. **Report findings** with counts per coverage state
+
+```
+# Example workflow
+Step 1: wp_list_posts status="publish" per_page=100 → Array of posts with links
+Step 2: For each post.link → gsc_inspect_url inspection_url=post.link
+Step 3: Group by coverageState → { indexed: 85, not_indexed: 12, errors: 3 }
+```
+
+### Sitemap vs index comparison
+
+Compare sitemap-submitted URLs against indexed URLs to find coverage gaps:
+
+1. **List sitemaps** with `gsc_list_sitemaps` to get submitted/indexed counts
+2. **Calculate coverage rate**: `indexed / submitted * 100`
+3. **Investigate gaps**: If coverage is below 90%, inspect non-indexed URLs individually
+
+## Handling Indexing Issues
+
+### Crawled but not indexed
+
+This means Google fetched the page but deemed it unworthy of indexing. Common causes:
+- **Thin content**: Page has very little unique content
+- **Duplicate content**: Substantially similar to another indexed page
+- **Low quality**: Content does not meet quality thresholds
+
+**Actions:**
+1. Inspect the URL with `gsc_inspect_url` to confirm the status
+2. Review the page content — add depth, unique value, or original research
+3. Check for duplicate content — use canonical tags to consolidate
+4. After improving, request re-indexing (not available via API; use Search Console UI)
+
+### Discovered but not indexed
+
+Google knows the URL exists but has not crawled it. This often indicates:
+- **Crawl budget**: The site has too many pages relative to its authority
+- **Internal linking**: The page is poorly linked from other pages
+- **Priority**: Google does not consider the page important enough to crawl
+
+**Actions:**
+1. Improve internal linking to the page from high-authority pages
+2. Add the URL to the sitemap if it is not already included
+3. Reduce crawl waste by blocking thin/utility pages with `noindex`
+
+### Blocked by robots.txt
+
+```
+# Check if the URL is blocked
+Tool: gsc_inspect_url
+Params:
+  inspection_url: "https://example.com/admin-page/"
+
+# If robotsTxtState is "DISALLOWED", review the robots.txt file
+```
+
+Ensure your `robots.txt` is not accidentally blocking important content pages.
+
+## Best Practices
+
+- **Sitemap freshness**: WordPress SEO plugins (Yoast, Rank Math) auto-generate sitemaps; submit the index sitemap once and let the plugin manage updates
+- **Inspection frequency**: Do not over-inspect; GSC has API quotas. Batch inspections for weekly or monthly audits
+- **New content**: After publishing a significant post, inspect it after 48-72 hours to verify crawling
+- **Redirect chains**: Avoid chains of 3+ redirects; they slow crawling and may cause indexing issues
+- **Status codes**: Regularly check for soft 404s — pages that return 200 but appear empty or error-like to Googlebot
+- **Canonical tags**: Ensure every page has a self-referencing canonical or points to the preferred version
+- **Crawl budget**: For large sites (10,000+ pages), prioritize indexing of high-value pages by improving internal linking and reducing index bloat
+- **Mobile-first**: Google uses mobile crawling by default; ensure `crawledAs: "MOBILE"` succeeds for all important pages

package/skills/wp-search-console/references/keyword-tracking.md

@@ -0,0 +1,181 @@
+# Keyword Tracking
+
+## Overview
+
+Keyword tracking uses GSC search analytics data to monitor how your WordPress site ranks for specific queries in Google Search. The `gsc_search_analytics` and `gsc_top_queries` tools provide clicks, impressions, CTR, and average position data that can be filtered by date range, query, page, country, and device.
+
+## Core Tools
+
+### Get top queries
+
+```
+Tool: gsc_top_queries
+Params:
+  site_url: "https://example.com/"
+  start_date: "2026-02-01"
+  end_date: "2026-02-28"
+  row_limit: 50
+Returns: Array of queries with clicks, impressions, ctr, position
+```
+
+This returns the top-performing queries ranked by clicks. Use `row_limit` to control how many queries are returned (default: 25, max: 25000).
+
+### Query search analytics with dimensions
+
+```
+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: 100
+Returns: Array of rows with keys (query, page), clicks, impressions, ctr, position
+```
+
+Available dimensions:
+- `query` — the search query text
+- `page` — the URL that appeared in search results
+- `country` — ISO 3166-1 alpha-3 country code
+- `device` — DESKTOP, MOBILE, or TABLET
+- `date` — individual date breakdown
+
+### Filter by specific query
+
+```
+Tool: gsc_search_analytics
+Params:
+  site_url: "https://example.com/"
+  start_date: "2026-02-01"
+  end_date: "2026-02-28"
+  dimensions: ["query", "date"]
+  dimension_filter_groups:
+    - filters:
+        - dimension: "query"
+          operator: "contains"
+          expression: "wordpress seo"
+  row_limit: 100
+```
+
+Filter operators:
+- `contains` — query contains the expression
+- `equals` — exact match
+- `notContains` — excludes queries containing the expression
+- `notEquals` — excludes exact matches
+
+## Tracking Position Changes Over Time
+
+### Daily position tracking
+
+To track how a keyword's position changes day by day:
+
+```
+Tool: gsc_search_analytics
+Params:
+  site_url: "https://example.com/"
+  start_date: "2026-02-01"
+  end_date: "2026-02-28"
+  dimensions: ["query", "date"]
+  dimension_filter_groups:
+    - filters:
+        - dimension: "query"
+          operator: "equals"
+          expression: "best wordpress plugins"
+  row_limit: 28
+```
+
+This returns one row per day for the specific query, showing position movement across the date range.
+
+### Compare periods
+
+To compare performance between two periods, make two `gsc_search_analytics` calls with different date ranges and compare the results:
+
+```
+# Period 1: Previous month
+Tool: gsc_search_analytics
+Params:
+  site_url: "https://example.com/"
+  start_date: "2026-01-01"
+  end_date: "2026-01-31"
+  dimensions: ["query"]
+  row_limit: 100
+
+# Period 2: Current month
+Tool: gsc_search_analytics
+Params:
+  site_url: "https://example.com/"
+  start_date: "2026-02-01"
+  end_date: "2026-02-28"
+  dimensions: ["query"]
+  row_limit: 100
+```
+
+Compare `position`, `clicks`, and `impressions` between periods to identify improving and declining keywords.
+
+## Query-Level Analysis
+
+### High-impression, low-CTR queries
+
+These are queries where your page appears frequently but users rarely click — indicating a title or meta description optimization opportunity:
+
+```
+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: 200
+```
+
+Filter results where `impressions > 100` and `ctr < 0.02` (2%). These queries should be prioritized for title tag and meta description improvements.
+
+### Position 4-20 keywords (striking distance)
+
+Keywords ranking on positions 4-20 are in "striking distance" — small improvements can move them to page 1 or top 3:
+
+```
+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: 500
+```
+
+Filter results where `position >= 4` and `position <= 20` and `impressions > 50`. These are the highest-ROI optimization targets.
+
+### Device-specific rankings
+
+```
+Tool: gsc_search_analytics
+Params:
+  site_url: "https://example.com/"
+  start_date: "2026-02-01"
+  end_date: "2026-02-28"
+  dimensions: ["query", "device"]
+  row_limit: 100
+```
+
+Compare mobile vs desktop rankings. Significant position differences may indicate mobile usability issues.
+
+## Creating Keyword Dashboards
+
+Build a comprehensive keyword report by combining multiple queries:
+
+1. **Top 50 queries by clicks** — `gsc_top_queries` with `row_limit: 50`
+2. **Position trends for target keywords** — `gsc_search_analytics` with `dimensions: ["query", "date"]` filtered by target queries
+3. **Page-level performance** — `gsc_page_performance` to see which pages drive the most search traffic
+4. **Country breakdown** — `gsc_search_analytics` with `dimensions: ["query", "country"]` for geo-specific insights
+
+## Best Practices
+
+- **Date range selection**: Use at least 28 days of data for reliable averages; short ranges (< 7 days) produce noisy data
+- **Regular monitoring**: Track core keywords weekly to catch position drops early; monthly for trend analysis
+- **Segment by intent**: Group queries by intent (informational, transactional, navigational) to align with content strategy
+- **Position averages**: GSC reports average position weighted by impressions; a page ranking #1 for one query and #50 for another may show position 25
+- **Data freshness**: GSC data has a 2-3 day delay; do not expect same-day data
+- **Row limits**: Default row limit is 1000; for comprehensive audits, increase to 25000
+- **Branded vs non-branded**: Separate branded queries (containing your brand name) from non-branded to get a clearer picture of organic discovery
+- **Click vs impression trends**: Rising impressions with flat clicks indicates a CTR problem; rising clicks with flat impressions indicates improved CTR or rankings