/gsc-deep-dive

name: gsc-deep-dive
description: 'Use when the user wants Google Search Console data pulled directly into the session instead of manually screenshotting / CSV-exporting from search.google.com. Pulls top queries, top pages, coverage status, manual actions, security issues, and Core Web Vitals field data via the GSC API in one call. Triggers from "pull GSC data for example.com", "Search Console deep dive", "GSC queries last 90 days", "GSC coverage report", "GSC indexing status", "GSC manual actions check", "GSC Core Web Vitals field data". Removes the manual GSC click-through that is the friction point of every recovery / audit session.'
user-invocable: true
argument-hint: '[domain] [days?]'
allowed-tools: [Read, Write, Bash(node:*), Bash(curl:*)]
license: MIT
metadata:
  author: Max Schottke
  version: '0.5.4'
  category: marketing

GSC Deep Dive

Overview

Google Search Console is the canonical source for what users actually search and click on your site, plus Google's own assessment of indexability, manual actions, security, and Core Web Vitals field data. Most workflows force the user to manually open GSC, click through 5-7 reports, screenshot or CSV-export each, and paste into the Claude context.

This skill removes that friction: one config (service-account JSON or OAuth token), one command, full JSON dump. From there, [[post-core-update-recovery]], [[seo-outreach-report]], and [[ai-search-rescue]] consume the data directly.

When to use

• A site running active recovery — pull GSC weekly to track query / page / impression drift in one report
• An audit handoff — gather every GSC signal in one JSON before invoking [[seo-outreach-report]]
• Verifying a recommendation actually landed — re-pull after 2-4 weeks and diff against the previous snapshot
• A YMYL / B2B site — manual actions + security issues + indexation status are the YMYL-relevant signals
• An agency onboarding a client — first-call data gathering in <5 minutes

**Don't use for:**

• Real-time monitoring (GSC data lags ~2 days for fresh queries, ~7 days for impressions)
• Competitor data (GSC only shows your own property)
• Backlink analysis (GSC has a backlink view but [[seo-outreach-report]] / [[competitor-deep-audit]] pull DataForSEO's more complete dataset)

What gets pulled

Per run, the script writes a single JSON file containing:

| Field | Source | What it tells you | |-------|--------|-------------------| | `site` | config | The verified GSC property | | `period` | `start_date` / `end_date` | The window queried (default last 90 days) | | `top_queries` | searchanalytics.query (rows=500) | Top 500 queries by clicks: keyword, clicks, impressions, CTR, position | | `top_pages` | searchanalytics.page (rows=500) | Top 500 pages by clicks: URL, clicks, impressions, CTR, position | | `query_page_pairs` | searchanalytics.query+page (rows=1000) | What page ranks for what query (most useful for cannibalisation detection) | | `coverage` | urlInspection if site-level | Indexed vs not-indexed counts | | `last_crawl_dates` | urlInspection per top-10 URL | When Google last crawled each top page | | `manual_actions` | searchconsole.searchanalytics + sites.list | Any pending manual actions on the property | | `crawl_errors_summary` | searchanalytics aggregates | Page-level errors (4xx, 5xx, soft-404) the last 30 days | | `crux_field_data` | from PSI v5 (cross-reference) | LCP / CLS / INP per top URL — field data, not lab | | `search_appearance` | searchanalytics with searchAppearance dimension | SERP feature breakdown (AMP, video, FAQ, How-to, Sitelinks, AI Overview where exposed) | | `query_weekly_series` | searchanalytics date+query, ISO-week-bucketed, top 200 by clicks | Per-query weekly click series over `weekly_series_days` (default 480) — input for quiet-death detection |

Quick start

1. GCP setup (one-time)

a. Go to [console.cloud.google.com](https://console.cloud.google.com), create or select a project.

> **Do not use a Google AI Studio default project.** If your project ID looks like `gen-lang-client-XXXXXXXXXX`, that is an auto-generated AI Studio scratchpad project. Service accounts created in those projects often fail with "Email not found" when you later try to add them to Search Console in Step 2, because the AI Studio identity path is not the same as a regular GCP project. Create a fresh project from the Cloud Console project selector instead — any name works.

b. Library → enable **Google Search Console API** (also called "Search Console API"). c. Library → enable **PageSpeed Insights API** (for the CrUX cross-reference). d. IAM & Admin → Service Accounts → Create:

• Name: `seo-rescue-gsc`
• Role: none needed at GCP level

e. On the new service account → Keys → Add Key → JSON. Save the downloaded JSON file securely. Treat it like a password — see security model below.

> **If Step 2 fails with "Email not found"** despite waiting 12+ hours: the most likely cause is that the service account was created in an AI Studio default project (see warning above). Recreate in a fresh standard GCP project. Reported in [#26](https://github.com/maxschottke-spec/seo-survival-kit/issues/26).

2. Grant the service account access to your GSC property

a. Open [search.google.com/search-console](https://search.google.com/search-console), select your property. b. Settings (gear icon, bottom-left) → Users and permissions → Add user. c. Email = the service account's email (format: `seo-rescue-gsc@<your-project>.iam.gserviceaccount.com`, visible on the GCP service-account page). d. Permission = **Restricted** (read-only).

3. Local setup

Copy the template:

mkdir -p ~/.config/seo-rescue
mv ~/Downloads/<project>-<hash>.json ~/.config/seo-rescue/gsc-service-account.json
chmod 600 ~/.config/seo-rescue/gsc-service-account.json

Copy and edit the config:

cp plugins/seo-rescue/skills/gsc-deep-dive/gsc-config.example.json ./gsc-config.json
# edit gsc-config.json:
#   "site": "sc-domain:ex