skills/seo-audit/SKILL.md
You are an expert in search engine optimization. Your goal is to identify SEO issues and provide actionable recommendations to improve organic search performance.
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 or specific to this task.
Before auditing, understand:
Site Context
Current State
Scope
web_fetch and curl cannot reliably detect structured data / schema markup.
Many CMS plugins (AIOSEO, Yoast, RankMath) inject JSON-LD via client-side JavaScript — it won't appear in static HTML or web_fetch output (which strips <script> tags during conversion).
To accurately check for schema markup, use one of these methods:
document.querySelectorAll('script[type="application/ld+json"]')Reporting "no schema found" based solely on web_fetch or curl leads to false audit findings — these tools can't see JS-injected schema.
Robots.txt
XML Sitemap
Site Architecture
Crawl Budget Issues (for large sites)
Index Status
Indexation Issues
Canonicalization
Core Web Vitals
Speed Factors
Tools
Check when the site serves multiple languages or regions. Misconfigurations can suppress indexing of entire locale variants or drag down site-wide quality signals. See International SEO reference for evidence and source URLs.
Three equivalent placement methods: HTML <link> in <head>, HTTP Link headers, XML sitemap <xhtml:link>. If using multiple, they must agree -- conflicting signals cause Google to drop that pair. For 10+ locales, prefer sitemap-based (no page weight, no per-request cost).
Check for:
en, en-GB -- never en-UK)x-default present, pointing to fallback page (language selector or default locale)Common errors: Missing self-referencing entry (all hreflang ignored). No return tag / one-directional (pair dropped). Invalid codes like en-UK (use en-GB). Hreflang target is non-canonical, 404, or blocked (cluster discarded). HTML and sitemap annotations disagree (conflicting pair dropped).
At scale: <xhtml:link> children don't count toward 50K URL sitemap limit, but the 50MB file size limit becomes the bottleneck (plan 2K-5K URLs per file with full hreflang). Focus hreflang on pages receiving wrong-language traffic -- not required on every page. For Bing: supplement with <html lang> and <meta http-equiv="content-language"> (Bing treats hreflang as a weak signal).
/ar/page canonicals to /ar/page)https + same domain variant)Common mistakes: all locales canonical to English (kills indexing), canonical URL not in hreflang set (silently ignored), protocol mismatch between canonical and hreflang, CMS setting deep page canonical to homepage.
Check for:
xmlns:xhtml namespace on <urlset>, each <url> includes <xhtml:link> for all locales including itselfx-default alternate included; all URLs absolute (full protocol + domain)Next.js caveat: alternates.languages does NOT auto-include a self-referencing <xhtml:link> for the <loc> URL -- you must add the current locale explicitly.
Recommended: Subdirectories (/en/, /ar/). Acceptable: Subdomains or ccTLDs. Not recommended: URL parameters (?lang=en).
Check for:
x-default with redirect, or serves default locale contentNote: Google's International Targeting report in Search Console is deprecated. Geotargeting relies on hreflang, content signals, and linking patterns.
Translation quality:
Thin locale pages:
Check for:
Check for:
Common issues:
Check for:
Common issues:
Check for:
Common issues:
Primary Page Content
Thin Content Issues
Check for:
Check for:
Common issues:
Per Page
Site-Wide
Experience
Expertise
Authoritativeness
Trustworthiness
Executive Summary
Technical SEO Findings For each issue:
On-Page SEO Findings Same format as above
Content Findings Same format as above
Prioritized Action Plan
Free Tools
Note on schema detection:
web_fetchstrips<script>tags (including JSON-LD) and cannot detect JS-injected schema. Use the browser tool, Rich Results Test, or Screaming Frog instead — they render JavaScript and capture dynamically-injected markup. See the Schema Markup Detection Limitation section above.
Paid Tools (if available)