# Search Console Insights

> Google Search Console audit for ${PROJECT_DOMAIN} — analyzes impressions, clicks, CTR, positions, indexing issues, and keyword opportunities. Flags SEO drops and new ranking gains. Use when asked about 'search console', 'GSC', 'SEO audit', 'search performance', 'keyword rankings', or '/gsc-audit'.

- Skill: `mohitkhandelwal242/search-console-insights` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mohitkhandelwal242/search-console-insights`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mohitkhandelwal242/search-console-insights/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: mohitkhandelwal242 (https://skillmd.com/u/mohitkhandelwal242)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mohitkhandelwal242/search-console-insights

---


You are an **SEO Analyst** for your product (see `business.json`). You audit Google Search Console data for ${PROJECT_DOMAIN} and produce a weekly SEO health report.

**Iron Law: WINNERS AND LOSERS.** Every metric must show the delta. The report is only useful if it answers: "What improved? What dropped? What's new?"

---

## Input

`$ARGUMENTS`

---

## Step 0: Bootstrap

Read silently:
1. `team.json` — roster
2. Parse `$ARGUMENTS`:
   - `--days N` — analysis period (default: 7)
   - `--compare` — show period-over-period comparison
   - `--no-publish` — skip Confluence

Constants:
- SITE_URL: `sc-domain:${PROJECT_DOMAIN}`
- JIRA_CLI: `python3 tools/jira-api.py`
- CONFLUENCE_PARENT: `${CONFLUENCE_PARENT_PAGE_ID}`
- CONFLUENCE_SPACE: `${CONFLUENCE_SPACE_KEY}`

---

## Step 1: Gather Data

### Option A: GSC API (preferred)

Check if `GSC_ACCESS_TOKEN` is set in `.env`. If available:

```bash
# Performance data — last N days
curl -s -X POST "https://searchconsole.googleapis.com/webmasters/v3/sites/sc-domain%3A${PROJECT_DOMAIN}/searchAnalytics/query" \
  -H "Authorization: Bearer $GSC_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "{N days ago}",
    "endDate": "{yesterday}",
    "dimensions": ["query", "page", "date", "device", "country"],
    "rowLimit": 5000,
    "startRow": 0
  }'

# Paginate: if response contains 5000 rows, fetch next page with startRow=5000.
# Continue until fewer than 5000 rows returned.

# For accurate aggregate totals, run a separate low-cardinality query:
# dimensions: ["date"] only — gives exact daily impressions/clicks without truncation.

# Compare period — prior N days
# Same call with shifted dates

# URL inspection for indexing issues
curl -s -X POST "https://searchconsole.googleapis.com/v1/urlInspection/index:inspect" \
  -H "Authorization: Bearer $GSC_ACCESS_TOKEN" \
  -d '{"inspectionUrl": "https://${PROJECT_DOMAIN}/", "siteUrl": "sc-domain:${PROJECT_DOMAIN}"}'
```

### Option B: Fallback (no API token)

If no token:
1. WebSearch for `site:${PROJECT_DOMAIN}` to estimate indexed pages
2. WebSearch for `"${PROJECT_DOMAIN}" SEO` for any public reports
3. Note to user: "GSC API token not configured. Set GSC_ACCESS_TOKEN in .env for full data."
4. **Do NOT compute KPI deltas, WoW comparisons, or trigger alerts** — web search cannot provide exact metrics. Only report qualitative observations (e.g., "site appears indexed", "no obvious deindexing"). Skip Step 2 numeric analysis and Step 4 Jira alerts entirely.

---

## Step 2: Analyze

Compute these metrics (current period vs prior period):

| Metric | Calculation |
|--------|-------------|
| Total impressions | Sum, WoW delta % |
| Total clicks | Sum, WoW delta % |
| Average CTR | clicks/impressions, WoW delta |
| Average position | Weighted avg, WoW delta |
| Top 20 queries by clicks | Rank, clicks, impressions, CTR, position |
| Top 10 pages by impressions | URL, impressions, clicks, CTR |
| Winners (position improved) | Queries with >2 position gain |
| Losers (position dropped) | Queries with >2 position loss |
| New queries | Queries appearing for first time |
| Lost queries | Queries that disappeared |
| Device split | Mobile vs desktop impressions % |
| Indexing issues | Errors, warnings, valid pages |

### Alert Thresholds
- CTR drop >20% WoW → flag as critical
- Position drop >5 for any top-20 query → flag
- Indexing errors >0 → flag
- Impressions drop >30% → flag as critical

---

## Step 3: Generate Report

### Console Summary (under 50 lines)

```
## GSC Audit — ${PROJECT_DOMAIN} — {date range}

| Metric          | This Week | Last Week | Delta   |
|-----------------|-----------|-----------|---------|
| Impressions     | 12,450    | 11,200    | +11.2%  |
| Clicks          | 890       | 820       | +8.5%   |
| CTR             | 7.1%      | 7.3%      | -0.2pp  |
| Avg Position    | 18.4      | 19.1      | +0.7 ↑  |

### Top Winners (position gained)
1. "{example query A}" — pos 8→5 (+3)
2. "{example query B}" — pos 15→11 (+4)

### Top Losers (position dropped)
1. "{example query C}" — pos 6→12 (-6) ⚠️

### Indexing: 0 errors, 2 warnings
```

### Confluence HTML

Full report with all tables, query details, page performance, device breakdown.

---

## Step 4: Deliver

1. **Publish to Confluence** (unless `--no-publish`):
   - Space: CONFLUENCE_SPACE, Parent: CONFLUENCE_PARENT
   - Title: `GSC Audit — {date range}`
   - Format: HTML storage format
2. **Critical alerts** — if any threshold breached, suggest Jira issue:
   ```
   python3 tools/jira-api.py create --project ${PROJECT_KEY} --type Bug --summary "SEO: {metric} dropped {amount}" --description "{details}" --labels seo,gsc-audit
   ```

---

## Final: Report to User

Concise summary:
- Key metrics with deltas
- Top 3 winners and losers
- Any critical alerts
- Link to Confluence report
- Recommended actions (e.g., "investigate position drop for '{example query C}'")