Google Search / Ads / Analytics - Knowledge Base + Agent Skills

A curated, validated local corpus of official Google documentation for Search/SEO, Search Console, Google Ads, and Google Analytics 4 - plus two Claude Code skills, two slash commands, and two multi-agent workflows that turn it into an AI-agent capability: cited retrieval and a multi-agent SEO audit.

Install (one line, in Claude Code)

/plugin marketplace add bsisduck/google-search-ads-analytics-docs

then /plugin install google-search-ads-analytics@bsisduck - the skills, /seo-audit and /google-docs commands, and the workflows are now available.

The corpus mirrors Google's own URL structure, carries YAML frontmatter with the original source_url on every page, and is validated (0 broken links, 0 duplicates, 0 error pages). The skills retrieve from it and answer with citations back to the official Google page - so an agent never has to guess about SEO, indexing, structured data, Search Console reports, Ads conversions, or GA4 measurement.

Not affiliated with Google. The pages under Docs/ are a local reference copy of official Google documentation, (c) Google, licensed CC BY 4.0. All tooling/code is MIT.

Why this exists

LLMs hallucinate Google's rules - the exact meta robots syntax, which JSON-LD props are required for a rich result, what a Search Console report column means. This repo grounds an agent in the real docs: ~1.3M tokens of reference content, too big for one context window but perfectly sized for agentic file search (locate 1-5 pages, read them whole, cite the source). A semantic vector sidecar covers conceptual / paraphrased queries where lexical search underperforms.

What's inside

<p align="center"> <img src="kb-map-final.png" alt="Corpus map" width="49%"> <img src="kb-flow-final.png" alt="Retrieval and audit flow" width="49%"> </p>

Quick start (from a clone)

Zero-install lexical search (stdlib only - works immediately):

python3 .claude/skills/google-search-ads-analytics-docs/search.py "block a page from indexing" --no-content

Full setup (semantic + hybrid retrieval, model daemon, the audit scanner):

./setup.sh                 # creates .venv and installs scrapling + sentence-transformers

Install the skills globally for Claude Code (alternative to the plugin, points at this clone):

./install-skills.sh        # copies skills to ~/.claude/skills, wires the corpus path

In Claude Code, the skills auto-trigger:

• ask "how do I block a page from indexing?" -> google-search-ads-analytics-docs
• ask "audit app/index.html for SEO" -> google-seo-audit

Using it

Retrieval (CLI)

# hybrid (best quality - lexical + dense, RRF-fused). Needs ./setup.sh
.venv/bin/python3 .claude/skills/google-search-ads-analytics-docs/hybrid.py "product structured data with price and rating"

# lexical only (no deps, ~0.4s, stem-aware ranking)
python3 .claude/skills/google-search-ads-analytics-docs/search.py "google ads conversion tracking" --top 5

# semantic only (paraphrase / conceptual queries)
.venv/bin/python3 .claude/skills/google-search-ads-analytics-docs/vec_search.py "make my products show up in search results"

Each result includes title, source_url, section, and a snippet. The agent reads the matched files whole and cites the source_url. The corpus is English (scraped from Google's hl=en pages).

Speed: start the model daemon once and hybrid/semantic queries drop to sub-second:

.venv/bin/python3 scripts/serve_models.py     # leave running

SEO audit

# snapshot a page (live URL or local file)
.venv/bin/python3 .claude/skills/google-seo-audit/fetch_page.py https://example.com/ --out /tmp/snap.json

In Claude Code, run /seo-audit <url-or-path> (or the google-seo-audit skill). It fans out one subagent per dimension (crawlability, on-page, structured data, page experience, international, tagging), grounds each in the docs skill, and writes a scored AUDIT-<page>.md with prioritized, cited fixes.

Only audit pages you own or are authorized to test.

Multi-agent workflows

Two reusable Workflow scripts in .claude/workflows/ encode Anthropic's orchestration best practices (pipeline fan-out, adversarial verification, synthesis) and scale agents to the work - no fixed cap:

• `seo-audit` - Snapshot -> Verify (one agent per SEO dimension) -> Refute

(adversarial verifiers per finding; false positives dropped) -> Synthesize a scored, cited AUDIT-<page>.md. Args: a URL or local path; optional { refuters: N }.

• `docs-research` - Decompose a question -> hybrid-retrieve and read per sub-question ->

Verify each claim against its cited source_url -> Synthesize one cited answer.

Retrieval architecture

Three composable paths (see KNOWLEDGE-BASE-ARCHITECTURE.md):

1. Lexical (search.py) - frontmatter-aware ranking over the English corpus, stdlib, instant.
2. Dense (vec_search.py) - multilingual-e5-small embeddings over **4,898 contextual

chunks** (each chunk prepends title | section, per Contextual Retrieval).

1. Hybrid (hybrid.py) - Reciprocal Rank Fusion of lexical + dense. Default best path.

Measured (scripts/eval_retrieval.py): English 92% recall@5 (MRR 0.84, hybrid); Polish->English cross-lingual 76%. A cross-encoder reranker is available (--rerank) but is opt-in. Run eval_retrieval.py --file data/eval_queries_en.json to reproduce.

Maintenance - reproducible pipeline

Licensing

• Code (scripts/, .claude/, app/, commands/, the *.py/*.sh/*.js) - MIT (see LICENSE).
• `Docs/` - official Google documentation, (c) Google, [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), retained here as a local reference copy. This project is unofficial and not endorsed by Google.

Contributing

See CONTRIBUTING.md. In short: keep the corpus reproducible (edit scripts/manifest.json, not files by hand), run scripts/validate.py before a PR, and don't commit secrets or machine-specific paths.