seo-hreflang
Skill2 starsChanged 5 months agoMITView on GitHub
Hreflang and international SEO audit for multi-language and multi-region sites. Validates language-region codes, return tags, x-default, canonical alignment, and conflict detection across the per-URL HTML (DataForSEO On-Page + Firecrawl/WebFetch) and the XML sitemap. Use when the user asks "hreflang", "international SEO", "i18n", "language targeting", "x-default", "regional sites", or "multi-language SEO".
33 other projects use a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- gaznil/seo-skills-by-gazniltheir own version, first seen Nov 16, 2026
- gaznilmuzammil12-prog/seo-skills-by-gazniltheir own version, first seen Nov 16, 2026
- martinbattaglia-commits/Claude-skillstheir own version, first seen Nov 16, 2026
- yotamwiesel/claude-skillstheir own version, first seen Nov 16, 2026
- joaoguirunas/team-ostheir own version, first seen Nov 15, 2026
- YerayRodri/claude-skillstheir own version, first seen Nov 13, 2026
Used with
Projects with it also use seo-agentic, seo-image-gen and 6 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
AgriciDanielSkillseo-agentic
Audit and fix agent readiness: the Lighthouse Agentic Browsing fraction, accessibility tree for agents, robots.txt and Content-Signal for AI agents, WAF treatment of agent traffic, llms.txt, Markdown delivery, ai-catalog.json, /.well-known discovery files, and WebMCP tools. Use when the user asks whether AI agents can use or browse the site, or about llms.txt or WebMCP. Exclude AI citability and brand signals (seo-geo) and commerce protocol depth (seo-ecommerce).
Also in 4 projects that use this
timruebenachSkillseo-image-gen
AI image generation for SEO assets: OG/social preview images, blog hero images, schema images, product photography, infographics. Powered by Gemini via nanobanana-mcp. Requires banana extension installed. Use when user says \"generate image\", \"OG image\", \"social preview\", \"hero image\", \"blog image\", \"product photo\", \"infographic\", \"seo image\", \"create visual\", \"image-gen\", \"favicon\", \"schema image\", \"pinterest pin\", \"generate visual\", \"banner\", or \"thumbnail\".
Also in 10 projects that use this
timruebenachSkillseo-dataforseo
Live SEO data via DataForSEO MCP server. SERP analysis (Google, Bing, Yahoo, YouTube, Google Images), keyword research (volume, difficulty, intent, trends), backlink profiles, on-page analysis (Lighthouse, content parsing), competitor analysis, content analysis, business listings, AI visibility (ChatGPT scraper, LLM mention tracking), and domain analytics. Requires DataForSEO extension installed. Use when user says "dataforseo", "live SERP", "keyword volume", "backlink data", "competitor data", "AI visibility check", "LLM mentions", "image SERP", "google images", "image rankings", or "real search data".
Also in 9 projects that use this
mangollcSkillseo-backlinks
Backlink analysis and link building strategy: competitor backlink profiling, outreach plan generation, monthly SEO reporting framework, toxic link identification, link opportunity scoring, and unlinked mention discovery.
Also in 11 projects that use this
- +4 more from timruebenach
Other versions33 projects use a version of this.
Word for word · 0
None found.
Edited · 1
- seranking/seo-skills★ 20186% same
Wrote their own version · 32
- AgriciDaniel/claude-seo★ 30ksame name
- zhtyyx/codex-seo★ 152same name
- coopersimson96/ai-content-system★ 17same name
- ZachArticulateV/designer-pro-and-seo★ 10same name
- joaoguirunas/team-os★ 6same name
- oegeyilmaz9/seo-aeo-geo-ultimate★ 6same name
- 01clauding/claude-seo-skill★ 4same name
- avalonreset/legends-seo-dungeon★ 4same name
- megastep/codex-skills★ 4same name
- realwigu/claude-skills★ 4same name
22 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository25 other files it gives its agents.
- seo-adsSkill
- seo-agency-landing-pageSkill
- seo-ai-search-share-of-voiceSkill
- seo-apiSkill
- seo-backlink-gapSkill
- seo-backlinks-profileSkill
- seo-competitor-gap-analysisSkill
- seo-competitor-pagesSkill
- seo-content-auditSkill
- seo-content-briefSkill
- seo-driftSkill
- seo-firecrawlSkill
- seo-geoSkill
- seo-googleSkill
- seo-imagesSkill
- seo-keyword-clusterSkill
- seo-keyword-nicheSkill
- seo-localSkill
- seo-pageSkill
- seo-planSkill
- seo-schemaSkill
- seo-sitemapSkill
- seo-subdomainSkill
- seo-sxoSkill
- seo-technical-auditSkill
The file
We split this skill into the rules it gives an agent
11 rules. 0 are common, 3 are distinctive, and 8 are very specific to this project.
0
Common
Most of the 33 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 33
If seo-technical-audit or seo-sitemap already ran, reuse their discovered URL set instead of re-discovering.
- Very specific: line 48
Return tags: every alternate link must reciprocate.
- Very specific: line 50
Language-region code validation: every value must be a valid ISO 639-1 language (optionally followed by - and an ISO 3166-1 Alpha-2 region).
- Very specific: line 52
Canonical alignment: if the page has <link rel="canonical">, it must match the page's own URL (or its self-referencing hreflang URL).
- Distinctive: line 53
Protocol consistency: all URLs in a set must share the same scheme (HTTPS preferred).
- Very specific: line 57
If the user's domain uses sitemap-based hreflang (<xhtml:link rel="alternate" …> inside the sitemap), this skill checks structure and …
- Distinctive: line 64
Cross-check against per-URL inventory (step 4): if a sample URL's HTML lists 4 hreflang alternates but the sitemap entry for that URL lists …
- Distinctive: line 72
If property not verified for a target domain: list it as a fix at Medium severity ("Verify {domain} in Google Search Console — required for …
- Very specific: line 78
Write HREFLANG-REPORT.md with the top-fixes table (top 10) and the verdict.
- Very specific: line 82
Create a folder seo-hreflang-{target-slug}-{YYYYMMDD}/ with:
- Very specific: line 172
Keep the sample small — homepage + ~5 language-spanning pages.
“Common” is measured: kept by at least 6 in 10 of the 33 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Example output: examples/seo-hreflang-airbnb-com-20260514/HREFLANG-REPORT.md
Hreflang Audit
Adapted from AgriciDaniel/claude-seo's seo-hreflang skill (MIT). Concept and validation rules originate there; this implementation is rebuilt against our backend (DataForSEO On-Page loop + Firecrawl + WebFetch + GSC + Google APIs via seo-google).
Validate hreflang implementations on a multi-language or multi-region site. Read the actual <link rel="alternate" hreflang="…"> tags pages emit — primarily from the DataForSEO on_page_instant_pages loop (which returns each page's hreflang set) plus Firecrawl/WebFetch for raw <head> markup — cross-check the XML sitemap's hreflang, weight by which country/language pages get impressions in GSC, and produce one of three verdicts — PASS, NEEDS-FIX, or BROKEN — with a top-fixes table anchored in objective signals.
Prerequisites
- DataForSEO MCP server connected —
on_page_instant_pagesreturns each fetched page's hreflang set, the primary signal source here. - GSC (
mcp__gscServer__*) recommended — for which country/language pages actually get impressions (traffic-weighting the audit) and cross-domain hreflang verification (step 6). Firecrawl optional — for raw<head>HTML where exact<link rel="alternate">attributes matter; WebFetch is the fallback. - Claude's
WebFetchtool available (fallback when Firecrawl is unavailable). - User provides: a target domain (e.g.
example.com). Optional: explicit list of representative pages to inventory; explicit sitemap URL if not at/sitemap.xml. - Predecessor (recommended):
seo-technical-auditorseo-sitemapalready run on this domain — its discovered URL set + On-Page hreflang fields can be reused. Without it, the skill discovers and fetches its own sample.
Optional accelerator: if you have a hosted-crawl MCP you can substitute it for the URL-discovery + fetch loop — not required.
Process
- Validate target & preflight. See
skills/seo-firecrawl/references/preflight.mdfor the canonical 3-stage preflight (cost note, Firecrawl availability, Google APIs). Skill-specific notes:- Normalise domain (strip protocol, trailing slash) before continuing.
- DataForSEO bills per call; this run issues ~5–10 calls (the homepage + ~5-sample
on_page_instant_pagesloop, plus up to ~6 Firecrawl credits for raw<head>markup). Use the documentedlimit/ceilingparams to cap. - Firecrawl: optional with WebFetch fallback, ~6 Firecrawl credits if available (hard cap). When available, step 4 (per-URL hreflang inventory) runs on homepage + 5 representative pages with
formats: ["rawHtml"]. Without Firecrawl, step 4 falls back to WebFetch — coverage is degraded because WebFetch returns markdown only and silently strips<link rel="alternate">tags from<head>. Pass--no-firecrawlto force WebFetch even when Firecrawl is available. - Google APIs: tier 1 (GSC) unlocks step 6 (GSC verification of hreflang-targeted alternates). See
skills/seo-google/references/cross-skill-integration.mdfor the full enrichment contract.
- Discover the URL set
mcp__firecrawl-mcp__firecrawl_map/WebFetch(sitemap) +mcp__gscServer__get_search_analytics+mcp__dataforseo__dataforseo_labs_google_relevant_pages- Build the candidate URL set for the audit: XML sitemap entries (especially any language-path branches like
/en/,/fr/,/de/), GSC indexed pages (dimensions=["page"]— surfaces which country/language URLs Google actually serves), and DataForSEO top pages. - If
seo-technical-auditorseo-sitemapalready ran, reuse their discovered URL set instead of re-discovering. - Cap to a representative sample (homepage + ~5 pages spanning the language paths). State the sample in the deliverable.
- Build the candidate URL set for the audit: XML sitemap entries (especially any language-path branches like
- Pull On-Page hreflang fields
mcp__dataforseo__on_page_instant_pages(looped)- Loop
on_page_instant_pagesover the sampled URLs — each result includes the page's<link rel="alternate" hreflang>set, its canonical, and status. This is the primary hreflang signal source (replacing a hosted crawl's hreflang report). - Extract every hreflang issue from these fields (typical codes:
hreflang_no_return_tag,hreflang_invalid_lang_code,hreflang_conflict,hreflang_missing_x_default,hreflang_canonical_mismatch,hreflang_no_self_reference). - Where the On-Page fetch's hreflang set looks incomplete (some sites inject alternates client-side or in unusual head order), confirm against the raw
<head>markup in step 4. - Persist to
01-audit-hreflang-issues.mdand feed intohreflang-issues.csv.
- Loop
- Per-URL hreflang tag inventory
mcp__firecrawl-mcp__firecrawl_scrape(preferred) /WebFetch(fallback)- Sample selection: homepage + up to 5 representative pages from
mcp__dataforseo__dataforseo_labs_google_relevant_pages(sort by traffic descending; bias toward pages on different language paths if the URL structure exposes them —/en/,/fr/,/de/, etc.). - Firecrawl path (1 credit per URL, ~6 total): call
firecrawl_scrape(url=..., formats=["rawHtml"]). PinrawHtml— the defaulthtmlpost-processing strips<link rel="alternate">on many sites. Parse every<link rel="alternate" hreflang="…" href="…">from the<head>. Capture: source URL, hreflang attribute, href, and whether it's self-referencing. - WebFetch fallback (no Firecrawl): try fetching each URL and extracting hreflang from the markdown response. WebFetch frequently returns markdown that has stripped
<head>link tags, so this path will under-report. Note inHREFLANG-REPORT.md:Per-URL inventory: degraded coverage — Firecrawl not installed; some hreflang tags may be missed. - Apply validation rules (see references/validation-rules.md for the full list):
- Self-referencing tag: the page's own URL must appear in its own hreflang set.
- Return tags: every alternate link must reciprocate. If page A lists B as
fr, page B must list A asen(or whichever). - x-default: at least one alternate per set must use
hreflang="x-default". - Language-region code validation: every value must be a valid ISO 639-1 language (optionally followed by
-and an ISO 3166-1 Alpha-2 region). Common errors caught:eng(useen),jp(useja),en-uk(useen-GB),es-LA(no such ISO region). - Conflict detection: the same hreflang value (e.g.
de-DE) appearing on multiple distinct URLs is a conflict — Google ignores conflicting sets. - Canonical alignment: if the page has
<link rel="canonical">, it must match the page's own URL (or its self-referencing hreflang URL). Hreflang on a non-canonical page is silently ignored by Google. - Protocol consistency: all URLs in a set must share the same scheme (HTTPS preferred).
- Persist to
02-per-url-hreflang.mdand append findings tohreflang-issues.csv.
- Sample selection: homepage + up to 5 representative pages from
- Sitemap-level hreflang (defer to
seo-sitemapwhere appropriate)- If the user's domain uses sitemap-based hreflang (
<xhtml:link rel="alternate" …>inside the sitemap), this skill checks structure and consistency only. Full sitemap analysis (orphans, missing pages, broken entries) isseo-sitemap's job — recommend it explicitly if a sitemap-vs-audit diff is in scope. - Fetch the sitemap. Try
https://{domain}/sitemap.xml; if 404, fetch/robots.txtand findSitemap:directives. For sitemap-of-sitemaps, recursively fetch each child. - Validate hreflang within the sitemap:
- Does the sitemap use the
xmlns:xhtml="http://www.w3.org/1999/xhtml"namespace? Required for hreflang in sitemaps. - Does each
<url>entry that has hreflang alternates include itself in the alternate set (self-reference)? - Does every alternate listed in one
<url>entry reciprocate as its own<url>entry with the same alternate set (return tags)? - Are language-region codes valid (apply same rules as step 4)?
- Does the sitemap use the
- Cross-check against per-URL inventory (step 4): if a sample URL's HTML lists 4 hreflang alternates but the sitemap entry for that URL lists 6, that mismatch is a conflict — Google may pick either, and inconsistency degrades the signal.
- Persist to
03-sitemap-hreflang.mdand append findings tohreflang-issues.csv.
- If the user's domain uses sitemap-based hreflang (
- GSC verification of hreflang-targeted alternates (only if google-api.json is present, tier ≥ 1)
- For each unique domain that appears as an
hreftarget in the hreflang sets (e.g.example.com,example.de,example.fr), confirm GSC verification:python3 scripts/gsc_query.py --property "{property}" --json(a status-only check; just confirm the property responds withoutPROPERTY_NOT_VERIFIED). - Why this matters: Google explicitly recommends verifying every domain that participates in a cross-domain hreflang setup. If
example.deis listed as an alternate but isn't verified in this account, the hreflang signal is weakened and you can't see how Google interprets it. - Surface in
HREFLANG-REPORT.mdas a section "## GSC verification of hreflang targets" with one row per target domain:verified/not verified/not configured. - If property not verified for a target domain: list it as a fix at Medium severity ("Verify {domain} in Google Search Console — required for cross-domain hreflang trust").
- See
skills/seo-google/references/cross-skill-integration.md§ "Trigger pattern" for the failure-mode contract.
- For each unique domain that appears as an
- Synthesise verdict
- Apply the verdict heuristic (see Tips) to produce PASS, NEEDS-FIX, or BROKEN.
- Sort
hreflang-issues.csvby severity descending, then count descending. - Write
HREFLANG-REPORT.mdwith the top-fixes table (top 10) and the verdict.
Output format
Create a folder seo-hreflang-{target-slug}-{YYYYMMDD}/ with:
seo-hreflang-{target-slug}-{YYYYMMDD}/
├── 01-audit-hreflang-issues.md (On-Page hreflang-field findings filtered to hreflang)
├── 02-per-url-hreflang.md (per-URL <link rel="alternate"> inventory + validation findings)
├── 03-sitemap-hreflang.md (sitemap-level hreflang validation; defer details to seo-sitemap)
├── evidence/
│ ├── homepage-rawhtml.html (raw HTML from Firecrawl, for the homepage sample)
│ ├── sample-{n}-rawhtml.html (raw HTML for each sampled URL)
│ └── sitemap.xml (raw fetched sitemap)
├── hreflang-issues.csv (load-bearing: URL, issue code, severity, fix)
└── HREFLANG-REPORT.md (PRIMARY: verdict + top fixes table)HREFLANG-REPORT.md follows this shape:
# Hreflang Audit: {domain}
> Audit date {YYYY-MM-DD} · Sample size: {n} URLs · Languages detected: {comma-separated list}
## Verdict: {PASS | NEEDS-FIX | BROKEN}
Reasoning: {1–2 sentences anchored in concrete numbers from the data}.
## Summary
| Source | Findings | Severity breakdown |
|---|---|---|
| On-Page hreflang fields | {n} | Critical: {n} · High: {n} · Medium: {n} · Low: {n} |
| Per-URL HTML inventory | {n} | … |
| Sitemap | {n} | … |
## Top fixes (impact-ranked)
| # | URL | Issue | Severity | Fix |
|---|---|---|---|---|
| 1 | {URL} | {issue code} | {severity} | {one-line fix} |
| 2 | … | … | … | … |
| ... up to 10 |
## Languages detected
| Language | URL count | Self-ref OK | Return tags OK | x-default OK |
|---|---|---|---|---|
| en-US | {n} | ✓ / ✗ {count} | ✓ / ✗ | ✓ / ✗ |
| de-DE | {n} | … | … | … |
| ... |
## Per-URL inventory ({n} URLs sampled)
| URL | Alternates | Self-ref | x-default | Notable issues |
|---|---|---|---|---|
| {URL} | {n} | ✓/✗ | ✓/✗ | {short text} |
| ... |
## Sitemap-level hreflang
- xhtml namespace declared: {✓/✗}
- URLs with hreflang alternates: {n}
- Self-reference within sitemap: {✓ all / ✗ {count} missing}
- Return tags within sitemap: {✓ all / ✗ {count} missing}
- Per-URL HTML vs sitemap consistency: {✓ all match / ✗ {count} mismatched}
- Full sitemap-vs-audit analysis: see `seo-sitemap` (orphans, broken entries, lastmod).
## GSC verification of hreflang targets
| Domain | Verified | Notes |
|---|---|---|
| {domain1} | ✓ / ✗ | {note if unverified} |
| ... |
(Or: `GSC verification: not configured (run bash extensions/google/install.sh)`.)
## Coverage notes
- Per-URL inventory tool: {Firecrawl rawHtml | WebFetch fallback (degraded — some hreflang tags may be missed)}.
- Pages sampled: homepage + {n} representative pages (selection: top traffic from `dataforseo_labs_google_relevant_pages`).
## Apply
- Walk `hreflang-issues.csv` row-by-row; each row is one specific change (URL + issue + fix).
- After applying changes, re-run `seo-technical-audit` to refresh the On-Page crawl baseline, then re-run this skill to verify.hreflang-issues.csv columns: url,issue_code,severity,fix,source where source is one of audit | html | sitemap | gsc (audit = the On-Page hreflang-field pass, step 3).
Tips
- DataForSEO allows up to 2,000 calls/min, 30 concurrent; pace sequentially.
- Keep the sample small — homepage + ~5 language-spanning pages. The per-URL
on_page_instant_pagesloop and Firecrawl raw-HTML pulls are the per-call cost here; a representative sample catches systemic hreflang errors without fetching every locale. - Verdict heuristic:
- PASS: zero Critical findings; ≤ 2 High findings; sample URLs all have self-reference, x-default, and reciprocal return tags; all language-region codes valid; canonical aligns with self-ref hreflang.
- NEEDS-FIX: any High finding; or > 5 Medium findings; or any one of (missing x-default, missing return tags on > 25% of sampled pages, language-region code error, sitemap-vs-HTML mismatch).
- BROKEN: any Critical finding; or hreflang attempted but no self-reference on the homepage; or canonical pointing elsewhere on a page that nonetheless emits hreflang (entire set is ignored by Google); or > 50% of sampled URLs missing return tags.
- Anchor every claim in
HREFLANG-REPORT.mdto a row inhreflang-issues.csv. If a stakeholder questions the verdict, walk them through the CSV. - For sites with > 50 language variants per page, the per-URL HTML implementation bloats the
<head>— recommend the sitemap-based implementation instead. Don't generate code; the deliverable is diagnostic, not code-gen. - The skill does not assess cultural adaptation, content parity, or locale formatting. Those are translation/QA concerns; they're orthogonal to whether hreflang itself is technically correct. If the user wants those, point them at the translation team — this skill answers "is the technical hreflang signal working?", not "is the localised content good?".
- For cross-domain hreflang (e.g.
example.com↔example.de), step 6's GSC check is the highest-value enrichment — verifying both domains is Google's explicit recommendation. - Common false-positive guard: if a sampled page legitimately has no internationalization (e.g. a single-region site), zero hreflang tags is correct, not an issue. The skill detects this by checking whether any sampled page emits hreflang; if none do, the verdict is PASS with note "No hreflang implementation detected — single-language site."
- Pair with
seo-sitemapfor the sitemap-vs-audit diff; pair withseo-technical-auditfor full technical health. This skill is narrow: hreflang correctness only. - See
references/validation-rules.mdfor the full per-issue rule table (severity, detection logic, suggested fix).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

