gsc skill

safe

This skill queries Google Search Console to reveal SEO insights, indexing status, and opportunities for optimization across sites.

npx playbooks add skill openclaw/skills --skill gsc

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

3.0 KB

---
name: gsc
description: Query Google Search Console for SEO data - search queries, top pages, CTR opportunities, URL inspection, and sitemaps. Use when analyzing search performance, finding optimization opportunities, or checking indexing status.
---

# Google Search Console Skill

Query GSC for search analytics, indexing status, and SEO insights.

## Setup

1. **Credentials**: Uses same OAuth credentials as GA4 skill (stored in `.env`)
2. **Scopes**: Requires `webmasters.readonly` scope on your Google Cloud OAuth consent screen
3. **Access**: Your Google account must have access to the Search Console properties

## Commands

### List Available Sites
```bash
source /Users/admin/clawd/skills/gsc/.env && \
python /Users/admin/clawd/skills/gsc/scripts/gsc_query.py sites
```

### Top Search Queries
```bash
source /Users/admin/clawd/skills/gsc/.env && \
python /Users/admin/clawd/skills/gsc/scripts/gsc_query.py top-queries \
  --site "https://www.nutrient.io" \
  --days 28 \
  --limit 20
```

### Top Pages by Traffic
```bash
source /Users/admin/clawd/skills/gsc/.env && \
python /Users/admin/clawd/skills/gsc/scripts/gsc_query.py top-pages \
  --site "https://www.nutrient.io" \
  --days 28 \
  --limit 20
```

### Find Low-CTR Opportunities
High impressions but low click-through rate = optimization opportunities:
```bash
source /Users/admin/clawd/skills/gsc/.env && \
python /Users/admin/clawd/skills/gsc/scripts/gsc_query.py opportunities \
  --site "https://www.nutrient.io" \
  --days 28 \
  --min-impressions 100
```

### Inspect URL Indexing Status
```bash
source /Users/admin/clawd/skills/gsc/.env && \
python /Users/admin/clawd/skills/gsc/scripts/gsc_query.py inspect-url \
  --site "https://www.nutrient.io" \
  --url "/sdk/web"
```

### List Sitemaps
```bash
source /Users/admin/clawd/skills/gsc/.env && \
python /Users/admin/clawd/skills/gsc/scripts/gsc_query.py sitemaps \
  --site "https://www.nutrient.io"
```

### Raw Search Analytics (JSON)
```bash
source /Users/admin/clawd/skills/gsc/.env && \
python /Users/admin/clawd/skills/gsc/scripts/gsc_query.py search-analytics \
  --site "https://www.nutrient.io" \
  --days 28 \
  --dimensions query page \
  --limit 100
```

## Available Dimensions
- `query` - Search query
- `page` - Landing page URL
- `country` - Country code
- `device` - DESKTOP, MOBILE, TABLET
- `date` - Date

## Metrics Returned
- **clicks** - Number of clicks from search
- **impressions** - Number of times shown in search
- **ctr** - Click-through rate (clicks/impressions)
- **position** - Average ranking position

## SEO Use Cases

1. **Content Optimization**: Find high-impression/low-CTR pages → improve titles & descriptions
2. **Keyword Research**: See what queries bring traffic → create more content around them
3. **Technical SEO**: Check indexing status, find crawl issues
4. **Ranking Tracking**: Monitor position changes over time
5. **Sitemap Health**: Verify sitemaps are submitted and error-free

## Notes

- Data has ~3 day delay (GSC limitation)
- Credentials shared with GA4 skill
- URL inspection requires the page to be in the property

Overview

This skill queries Google Search Console to surface search analytics, indexing status, and actionable SEO insights. It returns top queries, top pages, low-CTR opportunities, URL inspection results, sitemaps, and raw search analytics for custom dimensions and metrics. Use it to identify optimization targets, monitor ranking trends, and verify index status quickly.

How this skill works

The skill authenticates using your Google OAuth credentials with the webmasters.readonly scope and calls Search Console APIs. It can list verified sites, fetch search analytics (clicks, impressions, CTR, position) across selectable dimensions, inspect individual URL indexing status, and list submitted sitemaps. Commands accept parameters for site, date range, limits, dimensions, and filters to tailor queries.

When to use it

When you need top queries and pages driving organic traffic.
To find high-impression, low-CTR pages for title/description testing.
When checking whether a page is indexed or has inspection issues.
To verify sitemaps are submitted and free of errors.
For exporting raw analytics (query + page + device, etc.) for further analysis.

Best practices

Ensure your Google account has access to the Search Console property before querying.
Use a 3–7 day buffer when interpreting recent changes (GSC data has ~3 day delay).
Start with broader date ranges (28 days) then narrow to investigate specific changes.
Filter by min impressions to focus on statistically meaningful CTR opportunities.
Combine query + page dimensions to map keywords to landing pages for targeted optimization.

Example use cases

List all verified properties to confirm which sites you can query.
Pull top-queries for the last 28 days to discover new keyword opportunities.
Run top-pages to identify pages driving the most clicks and impressions.
Find low-CTR opportunities (high impressions, low CTR) to prioritize title and meta description updates.
Inspect a single URL to confirm indexing status and troubleshoot coverage problems.
Fetch sitemaps to validate submission state and detect sitemap errors.

FAQ

What credentials are required?

The skill uses Google OAuth credentials with the webmasters.readonly scope; your account must have access to the property.

How fresh is the data?

Search Console data typically lags about three days, so recent changes may not appear immediately.

Can I request custom dimensions and metrics?

Yes — the search-analytics command accepts dimensions like query, page, country, device, and date along with limits and filters.