/blog-google

name: blog-google
description: >
  Credentialed Google API calls for a blog: PageSpeed Insights, CrUX history,
  Search Console performance and URL Inspection, GA4 organic traffic, Cloud NLP
  entities, YouTube video search, Google Ads Keyword Planner, and the Indexing
  API (job and livestream pages only). Uses the user's Google credentials,
  quotas, and sometimes billing, and asks for consent before the first call.
  Runs only on an explicit request: /blog google, "run PageSpeed on this blog
  URL", "pull my Search Console data", "inspect this URL's index status",
  "set up Google API credentials". Shares config with claude-seo at
  ~/.config/claude-seo/google-api.json.
user-invocable: true
argument-hint: "[setup|pagespeed|crux|crux-history|gsc|inspect|index|ga4|nlp|youtube|keywords|report|quotas] [url|property|query]"
license: MIT
metadata:
  author: AgriciDaniel
  version: "2.3.2"
  category: blog

Blog Google: Google API Data for Blog Performance

Bundled paths below use host Markdown substitution of `${CLAUDE_SKILL_DIR}`; it is not an exported shell variable. Resolve them before execution, quote paths, and refuse nonabsolute overrides. Pass `blog_reference_root` resolved from `${CLAUDE_SKILL_DIR}/../blog/references`, `blog_template_root` from `${CLAUDE_SKILL_DIR}/../blog/templates`, and needed sibling roots to agents. Read the main reference `orchestration-details.md` before loading project context; pass only its helper-fenced output to downstream agents.

Direct access to Google's SEO APIs for blog performance analysis. Provides real Chrome user metrics, indexation status, search performance, entity analysis, YouTube video discovery, keyword volumes, and PDF/HTML performance reports.

Most integrations have no usage fee within their documented quotas. Cloud Natural Language requires billing and can incur charges after its free monthly tier. Google Ads requires an eligible account and developer token. Never enable billing or make a paid request without explicit user approval.

Cost and consent gate (mandatory, read first)

This skill uses the user's Google credentials, quotas, and sometimes billing.

• **What it spends:** API quota on the user's Google Cloud project (small

buckets: YouTube `search.list` has its own bucket of 100 calls per day, URL Inspection allows 2,000 per day per site, the Indexing API 200 publish requests per day); Cloud Natural Language bills after 5,000 free units a month; Keyword Planner needs a Google Ads account.

• **What it writes externally:** `index` sends a notification to Google and

`setup` writes credential config under `~/.config/claude-seo/`. Everything else is read-only.

• **Consent:** before the FIRST call in a session that reads account data

(`gsc`, `inspect`, `ga4`, `keywords`), spends a small bucket (`youtube`, batch `inspect`), can bill (`nlp`), or writes (`index`, `setup`), name the command, the property or URL, the expected call count, and the quota or cost basis, then wait for an explicit yes. Free keyless-style reads such as `pagespeed` and `crux` on a public URL only need the call named.

• **No uncapped loops:** batch files are limited to what the user approved;

stop on the first quota error instead of retrying through it.

• **Skips:** report each skipped or unavailable command in ONE line for the

orchestrator's "Fallbacks and skips" summary, such as "Google: no credentials, skipped CrUX".

Persistent runtime directory

`CLAUDE_BLOG_RUNTIME_DIR` optionally selects one trusted absolute persistent root. This integration uses `<root>/blog-google/.venv`; NotebookLM also uses `<root>/blog-notebooklm/data` for its library, authentication and browser state. Without this override, the existing skill-local defaults stay in use. Google's shared credential config/token paths stay unchanged. No state is copied or migrated automatically, and ordinary runs never perform setup.

Preserve an existing validated operator override. For a plugin without one, explicitly pass the host-substituted `${CLAUDE_PLUGIN_DATA}/claude-blog-runtime` path on both setup and every later runner call. This is Markdown substitution, not an exported shell variable. Execute only once it is an absolute resolved path. Single quotes keep an unresolved placeholder literal so validation rejects it instead of expanding it to a different shell path:

CLAUDE_BLOG_RUNTIME_DIR='${CLAUDE_PLUGIN_DATA}/claude-blog-runtime' python3 "${CLAUDE_SKILL_DIR}/scripts/setup_environment.py" --check --json
CLAUDE_BLOG_RUNTIME_DIR='${CLAUDE_PLUGIN_DATA}/claude-blog-runtime' python3 "${CLAUDE_SKILL_DIR}/scripts/run.py" google_auth --check --json

Only explicit setup without `--check` installs dependencies. Standalone users keep the default unless they explicitly choose an absolute runtime root. Relative, unresolved, or linked managed subdirectories fail closed. Changing the root selects separate state; it never authorizes a migration or cleanup of the old root. Plugin persistent data follows the host's uninstall retention rules; preserve it explicitly when uninstalling if it is still needed.

Prerequisites

**Always check credentials before running any command:**

BLOG_SKILLS_DIR="${CLAUDE_BLOG_SKILLS_DIR:-${CLAUDE_SKILL_DIR}/..}"
case "$BLOG_SKILLS_DIR" in /*) ;; *) echo "ERROR: skills dir must be absolute" >&2; exit 1 ;; esac
python3 "$BLOG_SKILLS_DIR/blog-google/scripts/run.py" google_auth --check --json

**Config file:** `~/.config/claude-seo/google-api.json` (shared with claude-seo)

{
  "api_key": "YOUR_GOOGLE_API_KEY",
  "oauth_client_path": "/path/to/client_secret.json",
  "default_property": "sc-domain:example.com",
  "ga4_property_id": "properties/123456789",
  "ads_developer_token": "...",
  "ads_customer_id": "123-456-7890",
  "ads_login_customer_id": "123-456-7890"
}

If missing, read `${CLAUDE_SKILL_DIR}/references/auth-setup.md` and walk the user through setup.

Credential Tiers

| Tier | Detection | Av