seo-gsc-drops

name	seo-gsc-drops
description	Detect ranking drops and lost traffic using Google Search Console data. Compares the last 28 days against the prior 28-day period to surface pages and keywords with the biggest declines. Use when user says "GSC drops", "ranking drops", "lost traffic", "pages losing rankings", or "keyword drops".
allowed-tools	["Read","Bash","ToolSearch"]

GSC Drops — Ranking Drop Detection

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

Identifies pages and keywords that lost clicks between the last 28 days and the prior 28-day period. Sorts by biggest losses first. Highlights CRITICAL drops (>50% loss).

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 drops` 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 the two comparison periods (GSC has ~3 day delay):

currentEnd=$(date -v-3d +%Y-%m-%d)
currentStart=$(date -v-31d +%Y-%m-%d)
previousEnd=$(date -v-31d +%Y-%m-%d)
previousStart=$(date -v-59d +%Y-%m-%d)
echo "Current: $currentStart to $currentEnd | Previous: $previousStart to $previousEnd"

Execution

Step 1 — Page-level comparison: Call compare_performance with:

• siteUrl: the site property
• currentStartDate: currentStart
• currentEndDate: currentEnd
• previousStartDate: previousStart
• previousEndDate: previousEnd
• dimension: "page"
• limit: 500

Step 2 — Query-level comparison: Call compare_performance with the same date params but:

• dimension: "query"
• limit: 500

Post-processing:

• Filter Step 1 results to rows where clicksChange < 0 (pages that lost clicks)
• Filter Step 2 results to rows where clicksChange < 0 (queries that lost clicks)
• Sort both lists by clicksChange ascending (biggest losses first)
• For each row, calculate change percentage if not provided: changePercent = (clicksChange / previousClicks) * 100
• Mark rows with changePercent < -50 as CRITICAL

Output Format

## GSC Drops: [site property]
**Current Period:** [currentStart] to [currentEnd]
**Previous Period:** [previousStart] to [previousEnd]

### Top Dropping Pages
| Page URL | Current Clicks | Previous Clicks | Change | Change% | Severity |
|----------|---------------|-----------------|--------|---------|----------|
| [url] | [n] | [n] | [n] | [X.X%] | CRITICAL / — |
...

### Top Dropping Queries
| Query | Current Clicks | Previous Clicks | Change | Change% | Severity |
|-------|---------------|-----------------|--------|---------|----------|
| [query] | [n] | [n] | [n] | [X.X%] | CRITICAL / — |
...

**Note:** CRITICAL = more than 50% drop in clicks between periods.

Show top 25 dropping pages and top 25 dropping queries. Truncate long URLs to 60 characters with ... for readability. If no drops detected, report: "No pages or queries lost clicks between the two periods."