seo-gsc-overview

name	seo-gsc-overview
description	Show a Google Search Console performance dashboard for the last 28 days. Displays total clicks, impressions, CTR, and average position, plus top 25 queries and top 25 pages. Use when user says "GSC overview", "search console performance", "how is my site doing in Google", "clicks and impressions", or "show me my GSC data".
allowed-tools	["Read","Bash","ToolSearch"]

GSC Overview — Performance Dashboard

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

Shows actual GSC performance data for the last 28 days: total clicks, impressions, CTR, average position, top 25 queries, and top 25 pages.

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 overview` 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, e.g. example.com), call list_sites to help identify the correct property format registered in GSC.

Date Calculation

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

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

This gives a 28-day window ending 3 days ago.

Execution

Step 1 — Top Queries (28 days): Call query_search_analytics with:

• siteUrl: the site property
• startDate: calculated startDate
• endDate: calculated endDate
• dimensions: ["query"]
• rowLimit: 25

Step 2 — Top Pages (28 days): Call query_search_analytics with:

• siteUrl: the site property
• startDate: calculated startDate
• endDate: calculated endDate
• dimensions: ["page"]
• rowLimit: 25

Step 3 — Top Pages by Clicks: Call get_top_pages with:

• siteUrl: the site property
• startDate: calculated startDate
• endDate: calculated endDate
• sortBy: "clicks"
• limit: 25

Aggregation: From Step 1 results, compute totals by summing across all returned rows:

• Total Clicks = sum of all clicks
• Total Impressions = sum of all impressions
• Avg CTR = (sum of clicks / sum of impressions) * 100 — format as X.XX%
• Avg Position = weighted average of position by impressions

CTR display rule: API returns CTR as decimal (0.0523) — always multiply by 100 for display (show 5.23%).

Output Format

## GSC Overview: [site property]
**Period:** [startDate] to [endDate] (28 days)

### Summary
| Metric | Value |
|--------|-------|
| Total Clicks | [number] |
| Total Impressions | [number] |
| Average CTR | [X.XX%] |
| Average Position | [X.X] |

### Top 25 Queries
| Query | Clicks | Impressions | CTR | Position |
|-------|--------|-------------|-----|----------|
| [query] | [clicks] | [impressions] | [X.XX%] | [X.X] |
...

### Top 25 Pages
| Page URL | Clicks | Impressions | CTR | Position |
|----------|--------|-------------|-----|----------|
| [url] | [clicks] | [impressions] | [X.XX%] | [X.X] |
...

Sort queries by clicks descending. Sort pages by clicks descending. Truncate long URLs to 60 characters with ... for readability.