SEO Technical Audit

Example output: examples/seo-technical-audit-linear-app-20260514/TECH-AUDIT.md

Technical Audit

A one-shot technical SEO audit for a domain. Pulls SE Ranking's audit data, categorizes findings by area (crawlability, indexability, security, mobile, structured data, etc.), severity-sorts within each, and produces a top-10 fix list ranked by impact × effort.

Prerequisites

• SE Ranking MCP server connected.
• Claude's WebFetch tool available (used for sense-checking robots.txt and sitemap presence).
• User provides: a target domain (e.g. example.com). Optional: target country (default us), audit-page-limit override (default: rely on the existing audit's limit).

Process

1. Validate target & preflight. See skills/seo-firecrawl/references/preflight.md for the canonical 3-stage preflight (credit balance, Firecrawl availability, Google APIs). Skill-specific notes:

   • Normalise domain (strip protocol, trailing slash) before continuing.
   • Estimated SE Ranking cost for this skill: a re-check of an existing audit is cheap; creating a new audit is significantly more expensive and varies by page count. Surface the cost before deciding.
   • Firecrawl: optional. When available, step 8 (Modern signals checklist) runs on 5 sample URLs and /robots.txt, ~6 Firecrawl credits (hard cap). Without it, step 8 is skipped — JS-render canonical/noindex divergence, X-Robots-Tag headers, and AI-crawler robots-rule analysis are unavailable but the full technical-audit deliverable still ships. Pass --no-firecrawl to skip step 8 even when Firecrawl is available (saves credits).
   • Google APIs: tier 0 unlocks step 8b (CrUX field data); tier 1 also unlocks step 8c (per-URL GSC Inspection on top 5 traffic pages). See skills/seo-google/references/cross-skill-integration.md § "seo-technical-audit" for the full recipe and per-tier branches.

2. Find or create the audit DATA_listAudits

   • List audits for the domain.
   • If a recent audit exists (<30 days old), use it.
   • If older than 30 days, run DATA_recheckAudit to refresh.
   • If none exists, ask the user before creating a new one with DATA_createStandardAudit (it consumes credits).
   • Wait for DATA_getAuditStatus to report done before pulling the report.

3. Pull the audit report DATA_getAuditReport

   • Top-line metrics: pages crawled, health score, total issues by severity.
   • Issues grouped by category (crawlability, indexability, mobile, security, structured data, etc.).

4. Pull per-issue page lists DATA_getAuditPagesByIssue

   • For each significant issue (severity ≥ medium, count ≥ 5), pull the affected URLs.
   • This produces the actionable fix list.

5. Cross-reference key URLs DATA_getIssuesByUrl

   • For the top 5 pages by traffic (from DATA_getDomainKeywords's page aggregation, or homepage + key landing pages if no keyword data), pull all issues for those specific URLs.
   • This catches cases where one important page concentrates many issues.

6. Sense-check WebFetch

   • Fetch /robots.txt and /sitemap.xml directly.
   • Confirm the audit's findings match reality on these critical files (audits sometimes lag behind same-day deploys).
   • Extended security headers. WebFetch the homepage and 3 sample URLs (top-traffic landing pages from step 5, fall back to homepage + key landing pages if no keyword data); read response headers and flag any of:
     • csp_missing — Content-Security-Policy absent.
     • xframe_missing — X-Frame-Options absent (informational; CSP frame-ancestors supersedes).
     • xcontent_missing — X-Content-Type-Options not set to nosniff.
     • referrer_policy_missing — Referrer-Policy absent.
     • hsts_no_preload — Strict-Transport-Security present but preload directive missing AND domain not on the Chromium HSTS preload list.
   • Map findings via references/severity-mapping.md § Security and surface in evidence/02-issues-by-category/security.md (and inline into TECH-AUDIT.md's "By category → Security" section).

7. Categorize and prioritize using references/severity-mapping.md

   • Map each issue code to severity, fix, and effort estimate.
   • Score each finding: severity × affected-page-count / effort.
   • Build the top-10 fix list.

8. Modern signals checklist mcp__firecrawl-mcp__firecrawl_scrape

   • SE Ranking's audit crawler doesn't execute JS and doesn't expose response headers per page. This step surfaces what's invisible to it.
   • If Firecrawl available (~6 Firecrawl credits, hard cap): pick 5 sample URLs from the audit — bias toward high-traffic landing pages and pages already flagged with noindex / canonical issues. For each:
     • JS-rendered canonical vs initial-HTML canonical (js_canonical_mismatch). Compare metadata.canonical (after JS render) against the canonical the audit recorded. Flag any divergence — per Google's Dec-2025 JavaScript SEO guidance, when a canonical in raw HTML differs from one injected by JS, Google MAY use either one, making canonical decisions non-deterministic. JS-injected canonical changes silently break indexing on JS-heavy sites.
     • JS-rendered noindex. Check metadata.robots for noindex after render. Catches client-side-only noindex injection that the audit can't see.
     • X-Robots-Tag header. Read response headers from metadata. Flag any noindex / nofollow / none directives at the HTTP layer.
     • Dec-2025 JS-SEO risk detection (Google's December 2025 JavaScript SEO guidance — four risks the static crawler cannot detect):
       • Risk 1 — Rendering-budget cuts (js_render_budget). Compare initial-HTML body size to rendered-HTML body size. Flag pages where rendered HTML is <50% of initial HTML size after JS execution — indicates Google may exhaust its render budget before the page's actual content loads.
       • Risk 2 — Hydration mismatch. Already detected above via js_canonical_mismatch; rationale: per the Dec-2025 guidance Google may pick either canonical, so any drift is a real-world ranking risk, not just a tidiness issue.
       • Risk 3 — CSR pitfalls (js_csr_meta_drift). Diff initial-HTML <title>, <h1>, and <meta name="description"> against the same fields in the JS-rendered DOM. Flag any divergence — Google does not reliably index content that only appears post-render, so the empty/wrong initial values may be what gets indexed.
       • Risk 4 — Soft-404 from JS errors (js_soft_404). Flag rendered pages where body text content is <500 chars but the HTTP response status is 200. This pattern indicates a JS render failure that Google treats as a soft-404 — the page returns 200 (so it's "live") but contains no real content (so it's "empty").
     • Then make one additional call: firecrawl_scrape on /robots.txt (1 credit). Parse for AI-crawler User-Agent rules — GPTBot, ClaudeBot, PerplexityBot, Google-Extended, ChatGPT-User, Bytespider, CCBot. Surface allow/disallow scope per agent.
   • If Firecrawl unavailable: skip this step. Note in TECH-AUDIT.md: Modern signals (JS canonical/noindex divergence, X-Robots-Tag, AI-crawler robots.txt rules, Dec-2025 JS-SEO risks): skipped — Firecrawl not installed.

8b. CWV field data via CrUX (only if google-api.json is present, tier ≥ 0)

• SE Ranking's audit reports lab-only CWV (Lighthouse-flavoured estimates). CrUX returns actual Chrome user p75 metrics — the data Google ranks against.
• Run python3 scripts/pagespeed_check.py "https://{domain}" --crux-only --json for current p75 LCP / INP / CLS / FCP / TTFB.
• Run python3 scripts/crux_history.py "https://{domain}" --origin --json for the 25-week trend per metric (improving / stable / degrading).
• If CrUX has no field data ("insufficient data"), surface that and continue — low-traffic origins are common.
• Surface in TECH-AUDIT.md as a new section "## Core Web Vitals (field data)" with current p75 + trend per metric, source labelled "CrUX 28-day origin".