---
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'."
source: davidpc007/openclaw-marketing-skills
---

# 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:

- **`google_analytics`** — sessions and conversions by landing page and by
  source/medium. It answers "which pages lost traffic" and "what is organic
  worth", which is most of why this skill gets invoked.
- **`google_bigquery`** — where a Search Console export already lands, for an
  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

```bash
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](https://moz.com/google-algorithm-change)
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](references/setup-guide.md): Detailed OAuth and service account setup
- [Query Library](references/query-library.md): Pre-built API queries for common analyses
- [Algorithm Update Timeline](references/algorithm-updates.md): 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