| name | seo-google |
| description | Google's own SEO field data — PageSpeed Insights v5 + CrUX (real Chrome CWV, with 25-week history), Search Console (Search Analytics, URL Inspection, Sitemaps), Indexing API v3, GA4 organic traffic, YouTube/NLP/Knowledge-Graph/Web-Risk extras, and Ads Keyword Planner volume. Direct REST calls (curl via Bash, or WebFetch) against Google's own endpoints — bridges the gap between crawl-based analysis and what Google itself reports. Use when the user says "search console", "GSC", "PageSpeed", "CrUX", "field data", "indexing API", "GA4 organic", "URL inspection", or "real CWV data". |
| allowed-tools | Read, Write, Glob, Grep, Bash, WebFetch |
SEO Google — Field Data From Google's Own APIs
Crawl-based analysis is an estimate of what Google sees. These APIs are what Google actually reports: real Chrome user metrics, real indexation verdicts, real search performance. All of it is free.
When this skill activates
Implicit: "check Core Web Vitals field data", "pull Search Console data", "is this URL indexed", "GA4 organic traffic", "submit this URL to Google", "CrUX history for this domain".
Explicit: "Use the seo-google skill to [task]."
Routed from: [[seo]] orchestrator — conditionally, when a GSC/PSI/GA4 connection is available; [[seo-technical]] (real CWV field data to supplement Lighthouse lab scores); the campaign/write measure phase in /mk:seo campaign.
Scope
Covers:
- PageSpeed Insights v5 (Lighthouse lab scores) + CrUX field data + 25-week CrUX History trends.
- Search Console: Search Analytics (clicks/impressions/CTR/position), URL Inspection (single + batch), Sitemaps, Sites.
- Indexing API v3 (JobPosting/BroadcastEvent-eligible URLs only).
- GA4 Data API v1beta — raw
runReport/batchRunReports calls for organic-traffic breakdowns.
- YouTube Data API (video SEO), Cloud NLP (entity/sentiment diagnostics — not an E-E-A-T score), Knowledge Graph (brand entity check), Web Risk (malware/phishing flag check).
- Google Ads Keyword Planner (gold-standard search volume — the source DataForSEO itself resells).
- Credential setup (API key vs. service account), rate limits/quotas, and the DMA/consent-mode-v2 caveats that affect how EU GSC/GA4 numbers should be read.
- Markdown report templates for CWV audits, GSC performance, and indexation status.
Does NOT cover:
- Crawl-based technical audits (site architecture, robots/sitemap content, JS rendering) → [[seo-technical]]. This skill supplies the CWV field data that audit consumes; it doesn't crawl the site itself.
- DataForSEO-sourced SERP/backlink/keyword-difficulty data → [[seo-dataforseo]]. Google Ads Keyword Planner (this skill) is the upstream volume source; DataForSEO is a paid alternative when Ads API access isn't set up.
- Schema/JSON-LD generation → [[seo-schema]]. URL Inspection here reports which rich-result types Google detected; it doesn't generate the markup.
- AI-Overviews/AI-Mode citation strategy → [[seo-geo]]. This skill can pull the GSC Generative-AI performance report (impressions only) as one input to that work.
Boundary with mcp-gsc / mcp-ga4 (skills/automation/): those two skills are thin MCP-tool wrappers for the single most common GSC/GA4 read (searchAnalytics, sitemaps, one-URL inspectUrl, listSites; GA4 runReport) with a manual-CSV-export fallback when no MCP server is configured — reach for them first when an mcp__gsc__*/mcp__ga4__* tool is already wired up and covers the ask (simpler call surface, no auth wrangling). Use this skill when the ask needs something they don't expose — batch URL Inspection, sitemap submission, the Generative-AI performance report, DMA/consent-mode interpretation of the numbers — or for everything outside GSC/GA4 entirely (PSI/CrUX, Indexing API, YouTube, NLP, Keyword Planner, Knowledge Graph, Web Risk). Both paths hit the same Google APIs; don't run both for the same request.
Credential tiers
Check ~/.config/claude-seo/google-api.json (or GOOGLE_API_KEY / GOOGLE_APPLICATION_CREDENTIALS / GA4_PROPERTY_ID / GSC_PROPERTY env vars) before running anything. Full setup walkthrough: references/auth-setup.md.
| Tier | Detection | Unlocks |
|---|
| 0 — API key | api_key present | PageSpeed, CrUX, CrUX History, YouTube, NLP, Knowledge Graph, Web Risk |
| 1 — + Service account | OAuth token or service-account JSON | + Search Console (Analytics, Inspection, Sitemaps), Indexing API |
| 2 — + GA4 property | ga4_property_id configured | + GA4 organic traffic reports |
| 3 — + Ads access | ads_developer_token + ads_customer_id | + Keyword Planner (ideas, volume) |
Always state the detected tier before running a command, and name which of the sections below are unavailable at the current tier.
PageSpeed Insights + CrUX (field data)
Full endpoint/response reference: references/pagespeed-crux-api.md.
- PSI v5 (
GET https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=<url>&key=<key>) — Lighthouse lab scores (performance/accessibility/best-practices/SEO) plus a same-call CrUX snapshot. Google is migrating field data out of PSI, so prefer CrUX directly for field data and use PSI mainly for the lab scores.
- CrUX (
POST https://chromeuxreport.googleapis.com/v1/records:queryRecord, API key in X-Goog-Api-Key header) — 28-day p75 for LCP/INP/CLS/FCP/TTFB. 404 means insufficient Chrome traffic, not an auth error. CLS p75 is string-encoded ("0.05") — always parse as float.
- CrUX History (
POST .../records:queryHistoryRecord) — same request shape, returns up to 25 weekly collection periods as a timeseries. Updates Mondays ~04:00 UTC; watch for "NaN" density strings and null percentiles in ineligible periods.
Core Web Vitals thresholds (current as of 2026-07-09; INP replaced FID on 2024-03-12 — never reference FID):
| Metric | Good | Needs Improvement | Poor |
|---|
| LCP | ≤ 2,500ms | 2,500–4,000ms | > 4,000ms |
| INP | ≤ 200ms | 200–500ms | > 500ms |
| CLS | ≤ 0.1 | 0.1–0.25 | > 0.25 |
| FCP | ≤ 1,800ms | 1,800–3,000ms | > 3,000ms |
| TTFB | ≤ 800ms | 800–1,800ms | > 1,800ms |
Search Console
Full reference (request/response shapes, filters, pagination): references/search-console-api.md.
- Search Analytics (
POST .../webmasters/v3/sites/{siteUrl}/searchAnalytics/query) — clicks/impressions/CTR/position by query/page/country/device/date. 2–3 day lag, ~16 months of history. Query- and page-level rows can silently omit anonymized low-volume traffic, so never sum them for a site total — run a separate dimensionless aggregate query for that, and only present it as authoritative once it comes back complete. Detect quick wins: queries at position 4–10 with high impressions.
- AI surfaces (2026): the dedicated Generative AI performance report (impressions only, no clicks/CTR/position; Pages/Countries/Devices/Dates; 1,000-row cap) is the only clean way to see AI Overviews + AI Mode visibility — AI Mode traffic otherwise rolls into standard Web totals, so it can't be split out after the fact.
- Data-reliability caveat: a GSC logging bug made impressions/CTR/average-position unreliable from 2025-05-13 to 2026-04-27 (clicks unaffected, fixed forward-only, no backfill). Flag any trend that spans that window.
- URL Inspection (
POST .../urlInspection/index:inspect, single or batched from a file) — the indexation truth: verdict (PASS/FAIL/NEUTRAL/PARTIAL), coverage state, robots.txt state, indexing state, page-fetch state, Google-selected vs. user-declared canonical, detected rich-result types. Note that FAQPage (retired 2026-05-07) and HowTo (retired 2023) no longer produce rich results — don't expect them. Rate-limited to 2,000/day, 600/min per site.
- Sitemaps (
GET/PUT/DELETE .../sitemaps) — submitted-count/error/warning status only. This reports what was submitted, not what's indexed — use URL Inspection for the indexation truth on specific URLs.
Indexing API v3
Full reference: references/indexing-api.md.
POST https://indexing.googleapis.com/v3/urlNotifications:publish with {"url": ..., "type": "URL_UPDATED"|"URL_DELETED"} (batches of up to 100 via multipart/mixed). This API is scoped to JobPosting and BroadcastEvent/VideoObject pages only — always say so before using it on an ordinary page; a URL_UPDATED ping there only nudges a recrawl, no ranking benefit. For ordinary URLs: URL Inspection for a few, sitemaps for many. Quota: 200 publish/day (resets midnight Pacific), tracked per project.
GA4 organic traffic
Full reference (dimensions, metrics, filter expressions, Python example): references/ga4-data-api.md.
POST https://analyticsdata.googleapis.com/v1beta/{property=properties/*}:runReport filtered to sessionDefaultChannelGroup = "Organic Search". Useful dimensions: landingPage, pagePath, deviceCategory, country; metrics: sessions, totalUsers, bounceRate, engagementRate, keyEvents (replaced deprecated conversions). Token-budgeted, not request-counted — pass returnPropertyQuota: true to watch spend (25K tokens/day, 5K/hour, 10 concurrent per property).
GA4 "AI Assistants" channel (live ~2026-05-13): sessions from a recognized AI assistant (ChatGPT, Gemini, Claude, Deepseek, Copilot, Grok) get medium=ai-assistant — but it excludes Google AI Overviews/AI Mode, Perplexity needs separate verification, and most AI-referred sessions arrive referrer-less and land in Direct. Treat it as a floor on AI traffic, not the full count.
YouTube, NLP, Knowledge Graph, Web Risk
Free, API-key-only extras. Full references: references/youtube-api.md, references/nlp-api.md, references/supplementary-apis.md.
| API | Use | Quota |
|---|
| YouTube Data API v3 | Video SEO — search (search.list, 100 units), video details + top comments (videos.list/commentThreads.list, ~1 unit each) | 10,000 units/day |
| Cloud NLP | Entity/sentiment/classification diagnostics for internal content-quality checks — not a Google E-E-A-T score, never present it as one | 5,000 units/month free (entities/sentiment); billing must be enabled |
| Knowledge Graph Search | Brand/entity presence check — does the site have a Knowledge Panel, is the entity disambiguated | 100,000 reads/day |
| Web Risk | Malware/social-engineering flag check — can explain a deindexing | 6,000 QPM, 100K/month free |
Some third-party GEO research reports a correlation between YouTube mentions and AI-search visibility — treat that as a methodology-dependent signal, not a Google-sourced benchmark.
Keyword Planner (Google Ads)
Full reference: references/keyword-planner-api.md.
GenerateKeywordIdeas / GenerateKeywordHistoricalMetrics — the volume source DataForSEO itself resells, so this is the more direct read when Ads API access exists (developer token + customer ID, Tier 3). Without active ad spend on the account, volumes come back as bucketed ranges ("1K–10K") rather than exact numbers — say so when reporting a bucketed figure. Competition score measures advertiser competition, not organic ranking difficulty.
DMA / consent-mode v2 — reading EU numbers correctly
Full note: references/dma-consent-mode-v2.md. The Digital Markets Act (in force since 2024-03-07) and GA4/Ads consent-mode v2 change what EU numbers mean, not what to recommend:
- GSC: EU CTR comparisons that straddle 2024-03-07 aren't apples-to-apples — flag it, don't silently trend it.
- GA4: EU organic sessions under a "denied ad_storage / granted analytics_storage" consent default are systematically under-counted (conversion modelling fills the gap; raw counts stay low). Surface the consent-mode config if the GA4 admin API exposes it.
- Do not lecture on cookie-consent UX (legal/engineering, out of scope) and do not recommend "switch to cookieless attribution" — Google abandoned third-party-cookie deprecation in 2024 and confirmed in 2025 there's no standalone Chrome cookie prompt coming. Recommend consent-mode v2 + server-side tagging for EU compliance and signal recovery instead.
Rate limits & error handling
Consolidated table + exponential-backoff strategy: references/rate-limits-quotas.md.
| API | Per-minute | Per-day |
|---|
| PSI v5 | 240 | 25,000 |
| CrUX + History (shared) | 150 | unlimited |
| GSC Search Analytics | 1,200/site | 30M/project |
| GSC URL Inspection | 600/site | 2,000/site |
| Indexing API | 380 total | 200 publish |
| GA4 Data API | 10 concurrent | ~25K tokens |
| Scenario | Action |
|---|
| No credentials configured | Walk through references/auth-setup.md. List which Tier-0 (API-key-only) calls still work. |
403 on GSC/GA4 | Service-account client_email not added to the property, or wrong permission level. |
404 on CrUX | Insufficient Chrome traffic — not an auth error. Fall back to PSI lab data. |
429 | Exponential backoff (1s, 2s, 4s, 8s, 16s + jitter); honor Retry-After if present. |
| Indexing quota exceeded | Report the 200/day cap; prioritize the most important URLs; suggest sitemaps for the rest. |
Reports
After analysis, offer to write a markdown report from the templates in assets/templates/:
| Template | Fed by |
|---|
cwv-audit-report.md | PSI + CrUX + CrUX History |
gsc-performance-report.md | Search Analytics |
indexation-status-report.md | Batch URL Inspection |
Fill the {placeholder} fields from the API responses above; leave a field [NEEDS DATA] rather than inventing a number.
Key concepts
- Field data vs. lab data — CrUX/PSI's
loadingExperience block is real Chrome-user telemetry (field); Lighthouse's lighthouseResult is a single synthetic run (lab). Field data is the ranking signal; lab data is the diagnostic.
- Indexation truth — sitemaps report what was submitted; URL Inspection reports what Google actually did with it. Never infer indexation from a sitemap alone.
- Bucketed vs. exact volume — Keyword Planner without ad spend returns ranges, not point estimates. Report the range, don't collapse it to a fake midpoint.
- NLP entities are a diagnostic, not a score — Cloud NLP salience/sentiment inform internal content review; they are not Google's E-E-A-T weighting.
Output
- Inline findings in the conversation (CWV ratings, quick-win queries, indexation verdicts).
- A markdown report from
assets/templates/ when the user wants an artifact: plans/marketing/<site>/GOOGLE-API-REPORT-{domain}.md.
- Raw JSON saved alongside a report when the user needs it for a later
/mk:seo campaign measure cycle.
Cross-references
plans/marketing-context.md — required hub- [[seo]] — orchestrator; dispatches here when a GSC/PSI/GA4 connection is available
- [[seo-technical]] — consumes CrUX field data to supplement its Lighthouse lab audit
- [[seo-dataforseo]] — paid alternative for SERP/backlink/volume data when Ads API access isn't set up
- [[seo-geo]] — consumes the GSC Generative-AI performance report for AI-citation work
skills/automation/mcp-gsc/SKILL.md, skills/automation/mcp-ga4/SKILL.md — lighter MCP-tool wrappers for the single most common GSC/GA4 read; see the boundary note above.claude/workflows/marketing-rules.md — content quality rules
Provenance
Imported from AgriciDaniel/claude-seo and adapted for KitForge. The source skill drove all calls through its own claude-seo run <script>.py CLI harness, which ClauKit doesn't ship — adapted here to direct REST calls (curl via Bash, or WebFetch) against the same Google endpoints, with routing to mcp-gsc/mcp-ga4 noted where those wrappers already cover the ask. Endpoint shapes, quotas, and the 2026 GSC/GA4 AI-surface and DMA/consent-mode notes are preserved from source.
