search-console-connect

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.

Reaching the data — READ THIS FIRST

There is no search_console connector. GET /v1/integration/connectors/providers is the live list and Search Console is not on it, so a skill that dials Google's API here has no credential to do it with and no place to put one.

Say that, and offer what does answer the same questions:

source/medium. It answers "which pages lost traffic" and "what is organic worth", which is most of why this skill gets invoked.

org that set one up. Then the queries are SQL and the credential is one we hold.

Both go through the connect skill, which owns the flow.

What this replaced. The upstream version installed a vendor SDK, ran its own OAuth, and wrote a long-lived credential to a JSON file. That is a secret on a disk with no rotation path — and it would still be inventing an integration this platform does not have.

The remedy for the gap itself is upstream, not here: a search_console provider in hanzoai/cloud's integrations, alongside google_ads and google_analytics. This skill starts working the day that lands, with no edit.

Data Pull

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

Fetches:

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:

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:

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

Keyword Cannibalization Detector

Find queries where 2+ of your pages compete:

= 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%)
  1. [Page URL] — Ranking for XX queries in position 4-15
  1. [Topic] — XX queries, avg position 25, you're visible but losing

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

References

Related Skills