seo-gsc-cannibalization

name	seo-gsc-cannibalization
description	Detect keyword cannibalization by identifying queries where multiple pages are competing for the same ranking. Uses Google Search Console data to find queries appearing across 2 or more pages. Use when user says "keyword cannibalization", "same keyword multiple pages", "cannibalizing keywords", or "duplicate rankings".
allowed-tools	["Read","Bash","ToolSearch"]

GSC Cannibalization — Keyword Cannibalization Detection

@skills/seo/references/mcp-degradation.md @skills/seo/references/gsc-api-reference.md

Finds queries where multiple pages compete for the same ranking, causing them to cannibalize each other's traffic. Identifies the "winning" page and "losing" pages for each cannibalized keyword.

MCP Check

Before calling any GSC tool, verify the MCP is connected:

1. Use ToolSearch with query +google-search-console
2. If tools returned — note the actual tool name prefix, proceed to Inputs
3. If no tools returned — display the GSC MCP error template from references/mcp-degradation.md and stop:

## Google Search Console MCP Not Available

The `/seo gsc cannibalization` command requires the GSC MCP, which is not currently connected.

**What you can do:**
- Use `/seo technical <url>` for crawlability and indexability analysis (no live data)
- Use `/seo audit <url>` for a full static SEO audit

**To connect GSC MCP:**
- Install and configure a Google Search Console MCP server (see README for setup)
- Add it to ~/.claude/mcp.json at user scope (NOT project scope)
- Verify GSC property access before running commands (domain vs URL prefix format)
- See references/gsc-api-reference.md for property format details

Inputs

• site: The GSC property URL. Accept both formats:
  • Domain property: sc-domain:example.com
  • URL prefix: https://example.com or https://www.example.com
  • If user provides a bare domain (no prefix), call list_sites to identify the correct property format registered in GSC.

Date Calculation

Use Bash to calculate dates (GSC has ~3 day delay):

endDate=$(date -v-3d +%Y-%m-%d)
startDate=$(date -v-31d +%Y-%m-%d)
echo "endDate: $endDate | startDate: $startDate"

Execution

Step 1 — Pull query+page data: Call query_search_analytics with:

• siteUrl: the site property
• startDate: calculated startDate
• endDate: calculated endDate
• dimensions: ["query", "page"]
• rowLimit: 1000

Post-processing — detect cannibalization: Group the results by query. For each query:

• Count distinct page values
• If a query has 2 or more distinct pages → it is cannibalized
• Keep only cannibalized queries for the report

For each cannibalized query, identify:

• "Winning" page: the page with the most clicks for that query
• "Losing" pages: all other pages competing for the same query

Sort cannibalized queries by total impressions descending (highest-traffic cannibalization issues first).

CTR display rule: API returns CTR as decimal — multiply by 100 for display.

Output Format

## GSC Cannibalization Report: [site property]
**Period:** [startDate] to [endDate] (28 days)
**Cannibalized queries found:** [count]

### Cannibalized Keywords

#### Query: "[query]" ([total impressions] impressions)
| Role | Page URL | Clicks | Impressions | CTR | Position |
|------|----------|--------|-------------|-----|----------|
| WINNING | [url] | [n] | [n] | [X.XX%] | [X.X] |
| losing | [url] | [n] | [n] | [X.XX%] | [X.X] |

**Recommendation:** [recommendation based on situation]

[Repeat for each cannibalized query...]

### Summary
| Metric | Value |
|--------|-------|
| Total cannibalized queries | [count] |
| Total pages involved | [count] |
| Estimated lost clicks | [sum of losing page clicks] |

Recommendation logic:

• If winning page has much higher position (lower number): consolidate losing pages into winning page via redirect or canonical
• If positions are close (within 3): add canonical signals pointing from losing to winning page; consider merging content
• If the pages cover distinct subtopics: differentiate content more clearly or use internal links to signal hierarchy

If no cannibalization found, report: "No keyword cannibalization detected. Each query appears on only one page in the top 1000 results."