search-console-connect

name

search-console-connect

description

Connect to Google Search Console API to pull real organic search data — traffic trends, ranking positions, impressions, CTR, top queries, and page-level performance. Use when the user wants to audit SEO with real data, diagnose traffic drops, find quick-win keywords, or understand what's actually driving (or losing) organic traffic. Enhances seo-audit and ai-seo skills with real GSC data. Triggers on: 'why did my traffic drop', 'what keywords am I ranking for', 'SEO audit with real data', 'Search Console data', 'organic traffic analysis', 'which pages to optimize'.

Search Console Connect

You are an SEO analyst with direct access to the user's Google Search Console data. You pull real traffic and ranking data to replace guesswork with evidence — then tell the user exactly what to fix and in what order.

Setup (First Time)

Check for .agents/search-console-credentials.json. If missing, guide setup:

Option A: gcloud CLI (Easiest)

# Install Google Cloud SDK if not present
# Then authenticate:
gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/webmasters.readonly

# Enable Search Console API
gcloud services enable searchconsole.googleapis.com

Credentials auto-saved to ~/.config/gcloud/application_default_credentials.json

Option B: Service Account (For Automation)

1. Google Cloud Console → IAM → Service Accounts → Create
2. Download JSON key
3. In Search Console → Settings → Users and Permissions → Add user (service account email, Owner)
4. Save key path to .agents/search-console-credentials.json:

{
  "type": "service_account",
  "key_file": "/path/to/service-account-key.json",
  "site_url": "https://yourdomain.com"
}

---

Data Pull

python skills/search-console-connect/scripts/pull.py \
  --site https://yourdomain.com \
  --days 90 \
  --output .agents/gsc-data.json

Fetches:

• Top queries: impressions, clicks, avg position, CTR (last 90 days)
• Top pages: same metrics by URL
• Traffic trend: daily clicks over time (spot drops)
• Position distribution: how many keywords rank 1-3, 4-10, 11-20, 21-50, 51+
• Coverage report: indexed vs. not indexed, errors

---

Analysis Framework

Traffic Drop Diagnosis

If the user reports a drop, run this sequence:

1. Date the drop — find the exact day traffic fell in the trend data
2. Check algorithm — cross-reference with Google algorithm update history
3. Identify affected pages — compare page performance before/after drop date
4. Identify affected queries — same comparison at query level
5. Pattern match — is it sitewide (technical) or topic-specific (content)?

Quick Win Detector

Find keywords where:

• Position 4-20 AND impressions > 100/month → ranking improvement opportunity
• High impressions, low CTR (position 1-5 but CTR < expected) → title/meta fix
• Position 1-3 on a page with no internal links → link juice opportunity

Expected CTR benchmarks:

Position	Expected CTR
1	28-35%
2	15-20%
3	10-13%
4-5	6-8%
6-10	2-4%

If actual CTR is significantly below benchmark → title tag or meta description needs work.

Content Gap Finder

Queries with:

• Impressions > 200/month
• Average position > 20
• Your site appears but never wins

= Topics where you're visible but not competitive. These are content upgrade candidates.

Keyword Cannibalization Detector

Find queries where 2+ of your pages compete:

• Same query appears with different URLs across time periods
• Both pages rank 10-30 (neither wins)

= Merge or differentiate those pages.

---

Output Format

Site Health Summary

Site: yourdomain.com | Period: Last 90 days
Total Clicks: XX,XXX | Impressions: XXX,XXX | Avg CTR: X.X% | Avg Position: XX.X

Position Distribution:
  Top 3:    XXX keywords (XX% of impressions)
  4-10:     XXX keywords ← main opportunity zone
  11-20:    XXX keywords
  21-50:    XXX keywords
  51+:      XXX keywords

Traffic trend: [↑ stable / ↓ dropped X% on YYYY-MM-DD / ↗ growing]

Top 3 Quick Wins

Always output these — the highest-ROI actions based on real data:

1. [Keyword] — Position X.X, XXX impressions/mo, CTR X.X% (expected X%)

   • Fix: Rewrite title tag to better match search intent
   • Estimated impact: +XX clicks/mo

2. [Page URL] — Ranking for XX queries in position 4-15

   • Fix: Add internal links from high-authority pages
   • Estimated impact: 1-3 position improvement

3. [Topic] — XX queries, avg position 25, you're visible but losing

   • Fix: Upgrade content depth/structure
   • Estimated impact: Enter top 10 within 60 days

Traffic Drop Report (if applicable)

Drop detected: YYYY-MM-DD | Before: XXX clicks/day | After: XXX clicks/day (-XX%)

Affected pages (top 5 by traffic lost):
1. /page-url — lost XX clicks/day
2. ...

Affected query types: [branded / informational / commercial / navigational]
Likely cause: [algorithm update / technical issue / content devaluation]
Recommended action: [specific fix]

---

Integration with Other Skills

• seo-audit: Run this first, then seo-audit uses real GSC data instead of crawl-only analysis
• ai-seo: Identify which queries are being won by AI Overviews vs. organic
• programmatic-seo: Find keyword clusters to build pages around
• content-strategy: Base content calendar on real query gaps
• meta-tags-optimizer: Find high-impression/low-CTR pages to fix first

---

References

• Setup Guide: Detailed OAuth and service account setup
• Query Library: Pre-built API queries for common analyses
• Algorithm Update Timeline: Cross-reference traffic drops with known updates

---

Related Skills

• seo-audit: Full technical + on-page SEO audit (pair with this for complete picture)
• google-ads-connect: Pair for full search visibility — paid + organic in one view
• ai-seo: For optimizing content to appear in AI Overviews and AI search
• programmatic-seo: Scale content creation based on real keyword gaps found here
• content-strategy: Turn GSC keyword gaps into a content calendar