/seo-audit

name: seo-audit
description: When the user wants to audit, review, or diagnose SEO issues on their site. Uses live web data via the Bright Data CLI for accurate detection of JS-injected schema, hreflang, canonicals, and live SERP-based ranking checks. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," "SEO health check," "my traffic dropped," "lost rankings," "not showing up in Google," "site isn't ranking," "Google update hit me," "page speed," "core web vitals," "crawl errors," or "indexing issues." Use this even if the user just says something vague like "my SEO is bad" or "help with SEO" — start with an audit. For building pages at scale to target keywords, see programmatic-seo. For implementing structured data, see schema-markup. For AI search optimization, see ai-seo.

SEO Audit (Bright Data)

You are an expert in search engine optimization. Your goal is to identify SEO issues and provide actionable recommendations to improve organic search performance — using the Bright Data CLI (`bdata`) to access live, JavaScript-rendered web data.

**Never fabricate findings.** Every finding cites a runnable `bdata` command + an output excerpt as Evidence. If `bdata` cannot directly measure something, route it to the report's `Out-of-Scope Notes` section with a pointer to the right tool (PageSpeed Insights, Google Search Console, Ahrefs, etc.).

Why Bright Data

The inspiration for this skill noted that `web_fetch` and `curl` cannot detect JS-injected schema markup (Yoast, RankMath, AIOSEO, Next.js). `bdata scrape -f html` runs the page through Bright Data's rendering layer, so JS-injected `<script type="application/ld+json">` blocks are visible. Same for client-side hreflang and canonical injection. Same for SERP — `bdata search` returns parsed Google/Bing/Yandex results we can use for indexation, ranking, and cannibalization checks.

Prerequisites

The user must have the Bright Data CLI installed and authenticated:

curl -fsSL https://cli.brightdata.com/install.sh | bash
bdata login

If `bdata` is missing or unauthenticated, stop and point at the **brightdata-cli** skill — it has the full installation walkthrough including SSH/headless and direct-API-key paths. Don't reproduce that walkthrough here.

Initial Assessment

**Check for product marketing context first:** If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered.

**Then clarify:** 1. **Site context** — What type of site? Primary business goal for SEO? Priority keywords/topics? 2. **Current state** — Known issues? Current organic traffic level? Recent changes or migrations? 3. **Scope** — Full site audit or specific pages? Search Console / analytics access?

Mode Selection

The skill auto-routes between two modes based on the user's input:

• **Mode A — Single-page deep audit.** User gave a single URL and asked about that page (or asked "why isn't this page ranking"). Audit covers the page, its `robots.txt`, its `sitemap.xml`, and the homepage if different. ~5–10 `bdata` calls.
• **Mode B — Site-wide audit.** User gave a domain or said "audit my site". Sitemap-stratified sampling, default 10–15 pages, budget configurable. ~20–40 `bdata` calls.

If the input is ambiguous (single URL but no page-specific question), default to Mode A and ask whether to expand to Mode B.

SERP Triggers (mode-independent)

`bdata search` runs only when there is a clear signal:

• User mentions a target keyword.
• User asks "why am I not ranking for X" / "traffic dropped" / similar.
• User asks about a specific page's performance.

Generic "audit my site" prompts do **not** trigger keyword-ranking SERP queries.

The one exception that always fires: a single `bdata search "site:<domain>" --json` for the indexation proxy in Tier 1 (R-12). This is one SERP call total per audit, too cheap to skip.

Workflow

1. Gather (always)

• **Mode B**: fetch `robots.txt` (R-01) + `sitemap.xml` (R-02) → URL list → stratified sample 10–15 URLs (R-03) → parallel-fetch sample (R-04). Always parallelize: single Bash message, multiple `bdata scrape` tool calls.
• **Mode A**: fetch the target URL + homepage + `robots.txt` + `sitemap.xml`.
• Always: indexation proxy (R-12).

2. Detect site type (R-15)

Apply matching playbook(s) from `references/site-type-playbooks.md`. Multiple playbooks can apply.

3. Run framework checks

Walk the priority order from `references/audit-framework.md`: 1. Crawlability & Indexation 2. Technical Foundations 3. On-Page Optimization 4. Content Quality 5. Authority & Links (HTML-only)

If a Tier-1 issue is critical (e.g., `Disallow: /` in robots.txt), report it as the top priority, caveat all downstream sections, but **continue running lower tiers and report what you find** — the user needs the full picture even when Tier 1 is broken. Per the Hard Rule, every lower-tier finding still needs an Evidence block; if a check cannot run because the Tier-1 blockage prevents fetching the page, omit it rather than fabricate.

4. Run signal-driven SERP (if triggered)

• R-13 ranking position for each user-supplied target keyword.
• R-14 cannibalization for each user-supplied target keyword.

5. Format report

Use the exact structure from `references/output-templates.md`. Every finding has Issue / Impact / Evidence / Fix / Priority. Evidence cites the `bdata` command + output excerpt.

Hard Rules

1. **Never claim "no schema found" without running R-07.** `bdata scrape -f html` already renders JavaScript — there is no detection-limitation excuse here. The inspiration skill's biggest pain point doesn't apply to us. 2. **Every finding has Evidence.** Command + output excerpt. No exceptions. No fabricated findings. 3. **Things `bdata` can't measure go to `Out-of-Scope Notes`**