google-audit

google-audit

A read-only audit that maps a website's current state to the rules in docs/rules.yaml. Every rule cites a Google or provider doc URL; thresholds match Google's published numbers verbatim. The skill does NOT make recommendations beyond what the cited doc supports.

When to use

Trigger when the user asks any of:

• "audit my site", "audit example.com", "google audit", "google best practices check"
• "is my site AI-search ready", "AI Overviews readiness", "GEO audit"
• "core web vitals", "lcp/inp/cls check"
• "schema deprecation check" (FAQPage, HowTo, sitelinks search box)
• "are my AI bots allowed" (OAI-SearchBot, PerplexityBot, etc.)
• "crawlability", "robots.txt review"

Do NOT use for: keyword research, backlink analysis, content writing, competitor analysis, ranking strategy, paid ads.

How it runs

Preferred — one-shot orchestration:

SKILL_DIR="${CLAUDE_SKILL_DIR:-$(dirname "$(readlink -f "${BASH_SOURCE[0]:-$0}")")}"
pip install -q -r "$SKILL_DIR/requirements.txt"
bash "$SKILL_DIR/scripts/run_audit.sh" "$URL" --max-pages "${MAX_PAGES:-50}"

run_audit.sh runs all six steps below and writes audit.json + audit.md to /tmp/google-audit-<timestamp>/. Pass --out DIR to override the location, --no-lighthouse to skip the Lighthouse CLI step, --no-psi to skip PageSpeed Insights.

The six-step manual breakdown below is for when you need to invoke a single step (e.g. only re-render after editing the JSON, or only re-run schema validation after a deploy).

0. Check prerequisites

python "$SKILL_DIR/scripts/google_auth.py" --check

If PAGESPEED_API_KEY is missing, warn the user but continue — Lighthouse lab data still works locally; only CrUX field data is unavailable.

1. Crawl

OUT=/tmp/google-audit-$(date +%s)
mkdir -p "$OUT"
python "$SKILL_DIR/scripts/crawl_site.py" "$URL" --max-pages "${MAX_PAGES:-50}" --out "$OUT"

This writes $OUT/crawl.json with the list of pages. Sitemap-first; falls back to BFS. Respects robots.txt.

2. Site-level inspection

python "$SKILL_DIR/scripts/robots_inspect.py" "$URL" --out "$OUT/robots.json"
curl -s -L --max-time 10 "$URL/llms.txt" -o "$OUT/llms_txt.txt" 2>/dev/null || true

3. Per-page facts (parallel-friendly)

For each URL in $OUT/crawl.json, create $OUT/pages/<NNN>-<slug>/ and run:

# Fetch HTML
python "$SKILL_DIR/scripts/fetch_page.py" "$PAGE_URL" --output "$PAGE_DIR/page.html"

# Parse SEO elements
python "$SKILL_DIR/scripts/parse_html.py" "$PAGE_DIR/page.html" --url "$PAGE_URL" --json > "$PAGE_DIR/parsed.json"

# Inject the page URL into parsed.json (needed for hreflang reciprocity check)
python -c "
import json
p = json.load(open('$PAGE_DIR/parsed.json'))
p['_page_url'] = '$PAGE_URL'
with open('$PAGE_DIR/page.html') as f:
    html = f.read()
p['_viewport_present'] = ('name=\"viewport\"' in html) or (\"name='viewport'\" in html)
json.dump(p, open('$PAGE_DIR/parsed.json','w'), indent=2)
"

# Schema validation (deprecated types, self-serving reviews, expired entities)
python "$SKILL_DIR/scripts/schema_validate.py" "$PAGE_DIR/page.html" --out "$PAGE_DIR/schema.json"

# PageSpeed Insights (lab + CrUX field data) — skip if no API key
[ -n "$PAGESPEED_API_KEY" ] && python "$SKILL_DIR/scripts/pagespeed_check.py" "$PAGE_URL" --strategy mobile --json > "$PAGE_DIR/psi.json"

# Lighthouse CLI — optional, slower but exhaustive
which lighthouse >/dev/null && python "$SKILL_DIR/scripts/lighthouse_run.py" "$PAGE_URL" --out "$PAGE_DIR/lighthouse.json"

You can run pages in parallel (4 concurrent works well). Cap to --max-pages 10 for quick smoke audits.

4. Gather facts

python "$SKILL_DIR/scripts/gather_facts.py" "$OUT" --out "$OUT/facts.json"

Merges crawl + robots + per-page subreports into the fact-path schema used by docs/rules.yaml.

5. Evaluate rules

python "$SKILL_DIR/scripts/rules_engine.py" --facts "$OUT/facts.json" --rules "$SKILL_DIR/docs/rules.yaml" --out "$OUT/audit.json"

6. Render Markdown

python "$SKILL_DIR/scripts/render_report.py" "$OUT/audit.json" --out "$OUT/audit.md"

Show the user the verdict line and a summary, then the path to both artifacts.

Output

• audit.json — every rule × every page where applicable, with status (pass / fail / needs_improvement / nice_not_done / skipped), observed value, threshold, and source_url citing the Google doc.
• audit.md — human-readable: verdict header, severity summary table, failing-MUST callout, then findings grouped by category.

Scoring rubric (Google-pure)

Result	Verdict
Any MUST failing	Not Ready — fix before anything else
All MUST pass, ≥ 80 % SHOULD pass	Competitive — eligible across Google + other AI engines
All MUST + all SHOULD pass	Leading — content quality + entity authority + monitoring

NICE rules don't move the verdict; they're tracked separately.

Conflict resolutions baked in

The skill never emits outdated guidance. docs/rules.yaml reflects the May 2026 state of Google's docs:

• rel=next/prev — not recommended; NICE only ("harmless for Bing/a11y")
• FAQPage rich result — only for gov/health domains; else flagged as deprecated (sunset May 7, 2026)
• HowTo rich result — flagged as deprecated whenever present (retired 2024)
• Sitelinks search box (potentialAction.SearchAction) — flagged as deprecated (Nov 21, 2024)
• Dynamic rendering — flagged as deprecated for new builds
• Mobile-Friendly Test — never referenced (retired Dec 1, 2023); Lighthouse + PSI only
• FID — replaced by INP March 12, 2024; skill measures INP only
• Crawl-delay for Googlebot — flagged as ignored by Google
• Google-Extended as "AI Overviews opt-out" — explicitly NOT; only noindex / nosnippet control AI Overviews
• llms.txt — checked for presence only; reported informational, never as a ranking factor

Example invocations

/google-audit example.com
/google-audit https://example.com --max-pages 25
/google-audit blog.example.com --max-pages 10

What to tell the user when reporting

1. Lead with the verdict — "Not Ready / Competitive / Leading" from audit.md.
2. List failing MUSTs verbatim (status + title + page URL + fix hint + source URL).
3. Group SHOULD failures by category so the user can plan a sprint.
4. Cite the Google doc for every recommendation — never paraphrase without the link.
5. Don't invent rules. If the user asks about something not in rules.yaml, say so explicitly and offer to open a PR adding a rule with a Google-doc citation.

Limits and honest disclosure

• Field data (CrUX) requires real traffic. Low-traffic and newer sites get null CrUX values for LCP/INP/CLS — Google needs enough real-user data before they publish field metrics. This is expected and not a failure: the rules engine marks these rules as skipped, not fail. Install Lighthouse CLI (npm install -g lighthouse) for synthetic lab-data fallback when CrUX is unavailable.
• AI-citation monitoring is out of scope. This skill audits compliance, not whether AI engines actually cite the site — that needs third-party tools.
• The cross-LLM bot list evolves. OpenAI/Anthropic/Perplexity publish new agents and rename existing ones; treat the user-agent strings in robots_inspect.py as a snapshot, not a promise.
• No magic AI-only files. Google has explicitly stated no AI-specific markup is required. llms.txt is reported for presence only.