agentleFS
martinbattaglia-commitsmartinbattaglia-commits/Claude-skills/skills/seo-google/SKILL.md

seo-google

Skill0 starsChanged 5 months agoMITView on GitHub

Google SEO APIs: Search Console (Search Analytics, URL Inspection, Sitemaps), PageSpeed Insights v5, CrUX field data with 25-week history, Indexing API v3, and GA4 organic traffic. Provides real Google field data for Core Web Vitals, indexation status, search performance, and organic traffic trends. Use when user says "search console", "GSC", "PageSpeed", "CrUX", "field data", "indexing API", "GA4 organic", "URL inspection", "google api setup", "real CWV data", "impressions", "clicks", "CTR", "position data", "LCP", "INP", "CLS", "FCP", "TTFB", or "Lighthouse scores".

  • Reads credentials

20 other projects use a version of this, 14 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use seo-agentic and seo-firecrawl.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • AgriciDanielSkill

    seo-agentic

    Audit and fix agent readiness: the Lighthouse Agentic Browsing fraction, accessibility tree for agents, robots.txt and Content-Signal for AI agents, WAF treatment of agent traffic, llms.txt, Markdown delivery, ai-catalog.json, /.well-known discovery files, and WebMCP tools. Use when the user asks whether AI agents can use or browse the site, or about llms.txt or WebMCP. Exclude AI citability and brand signals (seo-geo) and commerce protocol depth (seo-ecommerce).

    Also in 4 projects that use this

  • amirjahfar1Skill

    seo-firecrawl

    Ad-hoc web scraping, site mapping, and full-site crawling via Firecrawl MCP. Returns raw HTML, parsed metadata (og:*, twitter:*, JSON-LD, canonical, robots), JS-rendered DOM, and screenshots that WebFetch cannot. Distinct from the DataForSEO skills (which give keyword/traffic/SERP data) and from WebFetch (which gives markdown prose only). Use when the user says "scrape this page", "crawl this site", "map this site", "find all pages on", "get the OG tags", "get the JSON-LD", "render this JS-heavy page", or any task where raw `<head>` metadata, structured-data scripts, or post-JS DOM are the actual deliverable. Also invoked as a sub-step from other skills that need raw HTML.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. 10 are common, 0 are distinctive, and 4 are very specific to this project.

  • 10

    Common

    Most of the 15 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    All APIs are free. Setup requires a Google Cloud project with API key and/or service account -- run /seo google setup for step-by-step …

    line 27
  2. Common:

    Before executing any command, check credentials:

    line 32
  3. Very specific:

    If missing, read references/auth-setup.md and walk the user through setup.

    line 47
  4. Common:

    Always communicate the detected tier before running commands.

    line 58
  5. Common:

    Search Analytics: clicks, impressions, CTR, position for last 28 days.

    line 122
  6. Common:

    Always inform the user of this restriction.

    line 165
  7. Common:

    Search YouTube for videos.

    line 199
  8. Common:

    Search volume for specific keywords (comma-separated).

    line 248
  9. Common:

    After any analysis command, offer to generate a PDF/HTML report.

    line 277
  10. Common:

    Run data collection commands (pagespeed, gsc, inspect-batch, etc.)

    line 293
  11. Very specific:

    Convention: After completing analysis, suggest: "Generate a report?

    line 297
  12. Common:

    Always include data freshness note

    line 325
  13. Very specific:

    Use templates from assets/templates/ for structured output

    line 327
  14. Common:

    Search Analytics data has 2-3 day lag.

    line 334

“Common” is measured: kept by at least 6 in 10 of the 15 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Google SEO APIs

Direct access to Google's own SEO data. Bridges the gap between crawl-based analysis (existing claude-seo skills) and Google's real-time field data: actual Chrome user metrics, real indexation status, search performance, and organic traffic.

All APIs are free. Setup requires a Google Cloud project with API key and/or service account -- run /seo google setup for step-by-step instructions.

Prerequisites

Before executing any command, check credentials:

python3 scripts/google_auth.py --check --json

Config file: ~/.config/claude-seo/google-api.json

{
  "service_account_path": "/path/to/service_account.json",
  "api_key": "<GOOGLE_API_KEY>",
  "default_property": "sc-domain:example.com",
  "ga4_property_id": "properties/123456789"
}

If missing, read references/auth-setup.md and walk the user through setup.

Credential Tiers

TierDetectionAvailable Commands
0 (API Key)api_key presentpagespeed, crux, crux-history, youtube, nlp
1 (OAuth/SA)+ OAuth token or service accountTier 0 + gsc, inspect, sitemaps, index
2 (Full)+ ga4_property_id configuredTier 1 + ga4, ga4-pages
3 (Ads)+ ads_developer_token + ads_customer_idTier 2 + keywords, volume

Always communicate the detected tier before running commands.

Quick Reference

CommandWhat it doesTier
/seo google setupCheck/configure API credentials--
/seo google pagespeed <url>PSI Lighthouse + CrUX field data0
/seo google crux <url>CrUX field data only (p75 metrics)0
/seo google crux-history <url>25-week CWV trend analysis0
/seo google gsc <property>Search Console: clicks, impressions, CTR, position1
/seo google inspect <url>URL Inspection: index status, canonical, crawl info1
/seo google inspect-batch <file>Batch URL Inspection from file1
/seo google sitemaps <property>GSC sitemap status1
/seo google index <url>Submit URL to Indexing API1
/seo google index-batch <file>Batch submit up to 200 URLs1
/seo google ga4 [property-id]GA4 organic traffic report2
/seo google ga4-pages [property-id]Top organic landing pages2
/seo google youtube <query>YouTube video search (views, likes, duration)0
/seo google youtube-video <id>YouTube video details + top comments0
/seo google nlp <url-or-text>NLP entity extraction + sentiment + classification0
/seo google entities <url-or-text>Entity analysis only (for E-E-A-T)0
/seo google keywords <seed>Keyword ideas from Google Ads Keyword Planner3
/seo google volume <keywords>Search volume lookup from Keyword Planner3
/seo google entity <query>Knowledge Graph entity check0
/seo google safety <url>Web Risk URL safety check0
/seo google quotasShow rate limits for all APIs--

PageSpeed + CrUX

/seo google pagespeed <url>

Combined Lighthouse lab data + CrUX field data.

Script: python3 scripts/pagespeed_check.py <url> --json Reference: references/pagespeed-crux-api.md Default: Both mobile + desktop strategies, all Lighthouse categories.

Output merges lab scores (point-in-time Lighthouse) with field data (28-day Chrome user metrics). CrUX tries URL-level first, falls back to origin-level.

/seo google crux <url>

CrUX field data only (no Lighthouse run). Faster.

Script: python3 scripts/pagespeed_check.py <url> --crux-only --json

/seo google crux-history <url>

25-week CrUX History trends. Shows whether CWV metrics are improving, stable, or degrading.

Script: python3 scripts/crux_history.py <url> --json Reference: references/pagespeed-crux-api.md

Output includes per-metric trend direction, percentage change, and weekly p75 values.


Search Console

/seo google gsc <property>

Search Analytics: clicks, impressions, CTR, position for last 28 days.

Script: python3 scripts/gsc_query.py --property <property> --json Reference: references/search-console-api.md Default: 28 days, dimensions=query,page, type=web, limit=1000.

Includes quick-win detection: queries at position 4-10 with high impressions.

/seo google inspect <url>

URL Inspection: real indexation status from Google.

Script: python3 scripts/gsc_inspect.py <url> --json

Returns: verdict (PASS/FAIL), coverage state, robots.txt status, indexing state, page fetch state, canonical selection, mobile usability, rich results.

/seo google inspect-batch <file>

Batch inspection from a file (one URL per line). Rate limited to 2,000/day per site.

Script: python3 scripts/gsc_inspect.py --batch <file> --json

/seo google sitemaps <property>

List submitted sitemaps with status, errors, warnings. Sitemap contents report submitted counts only; URL Inspection API is the indexation truth for whether specific URLs are indexed.

Script: python3 scripts/gsc_query.py sitemaps --property <property> --json


Indexing API

/seo google index <url>

Notify Google of a URL update.

Script: python3 scripts/indexing_notify.py <url> --json Reference: references/indexing-api.md

The Indexing API is officially for JobPosting and BroadcastEvent/VideoObject pages. Always inform the user of this restriction. Daily quota: 200 publish requests.

/seo google index-batch <file>

Batch submit URLs from a file. Tracks quota usage.

Script: python3 scripts/indexing_notify.py --batch <file> --json


GA4 Traffic

/seo google ga4 [property-id]

Organic traffic report: daily sessions, users, pageviews, bounce rate, engagement.

Script: python3 scripts/ga4_report.py --property <id> --json Reference: references/ga4-data-api.md Default: 28 days, filtered to Organic Search channel group.

/seo google ga4-pages [property-id]

Top organic landing pages ranked by sessions.

Script: python3 scripts/ga4_report.py --property <id> --report top-pages --json


YouTube (Video SEO)

YouTube mentions have the strongest AI visibility correlation (0.737). Free, API key only.

/seo google youtube <query>

Search YouTube for videos. Returns title, channel, views, likes, duration.

Script: python3 scripts/youtube_search.py search "<query>" --json Reference: references/youtube-api.md Quota: 100 units per search (10,000 units/day free).

/seo google youtube-video <video_id>

Detailed video info + tags + top 10 comments.

Script: python3 scripts/youtube_search.py video <video_id> --json Quota: 2 units (video details + comments).


NLP Content Analysis

Google's own entity/sentiment analysis. Enhances E-E-A-T scoring.

/seo google nlp <url-or-text>

Full NLP analysis: entities, sentiment, content classification.

Script: python3 scripts/nlp_analyze.py --url <url> --json or --text "..." Reference: references/nlp-api.md Free tier: 5,000 units/month. Requires billing enabled on GCP project.

/seo google entities <url-or-text>

Entity extraction only (faster, less quota).

Script: python3 scripts/nlp_analyze.py --url <url> --features entities --json


Keyword Research (Google Ads)

Gold-standard keyword volume data. Requires Google Ads account.

/seo google keywords <seed>

Generate keyword ideas from seed terms.

Script: python3 scripts/keyword_planner.py ideas "<seed>" --json Reference: references/keyword-planner-api.md Requires: Ads developer token + customer ID in config (Tier 3).

/seo google volume <keywords>

Search volume for specific keywords (comma-separated).

Script: python3 scripts/keyword_planner.py volume "<kw1>,<kw2>" --json


Supplementary

/seo google entity <query>

Knowledge Graph entity check. Verifies brand presence.

Reference: references/supplementary-apis.md Uses Knowledge Graph Search API with API key.

/seo google safety <url>

Web Risk API check for malware/social engineering flags.

Reference: references/supplementary-apis.md

/seo google quotas

Display rate limits table. Read references/rate-limits-quotas.md.


Reports

After any analysis command, offer to generate a PDF/HTML report.

/seo google report <type>

Generate a professional PDF report with charts and analytics.

Script: python3 scripts/google_report.py --type <type> --data <json> --domain <domain> --format pdf

TypeInputOutput
cwv-auditPSI + CrUX + CrUX History dataCore Web Vitals audit with gauges, timelines, distributions
gsc-performanceGSC query dataSearch Console report with query tables, quick wins
indexationBatch inspection dataIndexation status with coverage donut chart
fullAll data combinedComprehensive Google SEO report (all sections)

Workflow:

  1. Run data collection commands (pagespeed, gsc, inspect-batch, etc.)
  2. Save JSON output to file: python3 scripts/pagespeed_check.py <url> --json > data.json
  3. Generate report: python3 scripts/google_report.py --type cwv-audit --data data.json --domain <domain>

Convention: After completing analysis, suggest: "Generate a report? Use /seo google report <type>"


Rate Limits

APIPer-MinutePer-DayAuth
PSI v5240 QPM25,000 QPDAPI Key
CrUX + History150 QPM (shared)UnlimitedAPI Key
GSC Search Analytics1,200 QPM/site30M QPDService Account
GSC URL Inspection600 QPM2,000 QPD/siteService Account
Indexing API380 RPM200 publish/dayService Account
GA4 Data API10 concurrent~25K tokens/dayService Account

Cross-Skill Integration

  • seo-audit: Spawns seo-google agent for live CWV + indexation data (conditional)
  • seo-technical: Uses pagespeed_check.py for real CWV field data
  • seo-performance: CrUX field data supplements Lighthouse lab data
  • seo-sitemap: GSC sitemap status shows submitted counts, errors, and warnings; use URL Inspection for indexation truth
  • seo-content: GSC query data informs keyword targeting
  • seo-geo: GSC search appearance data includes AI Overview references

Output Format

  • CWV metrics: traffic-light rating (Good / Needs Improvement / Poor)
  • Performance reports: tables with sortable columns
  • Always include data freshness note
  • Save reports as GOOGLE-API-REPORT-{domain}.md
  • Use templates from assets/templates/ for structured output

Technical Notes

  • INP replaced FID on March 12, 2024. Never reference FID.
  • CLS values from CrUX are string-encoded (e.g., "0.05"). Scripts handle parsing.
  • CrUX 404 = insufficient traffic, not an auth error.
  • Search Analytics data has 2-3 day lag.
  • round_trip_time replaced effectiveConnectionType in CrUX (Feb 2025).
  • Custom Search JSON API is closed to new customers (2025).

Error Handling

ScenarioAction
No credentials configuredRun /seo google setup. List Tier 0 commands that work with just an API key.
Service account lacks GSC accessReport error. Instruct: add client_email to GSC > Settings > Users > Add.
CrUX data unavailable (404)Report insufficient Chrome traffic. Suggest PSI lab data as fallback.
GA4 property not foundReport error. Show how to find property ID in GA4 Admin > Property Details.
Indexing API quota exceededReport 200/day limit. Suggest prioritizing most important URLs.
Rate limit (429)Wait and retry with exponential backoff. Report which API hit the limit.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.