seo-hreflang
Skill0 starsChanged 3 days agoMITView on GitHub
Hreflang and international SEO audit, validation, and generation. Detects common mistakes, validates language/region codes, and generates correct hreflang implementations. Use when user says "hreflang", "i18n SEO", "international SEO", "multi-language", "multi-region", or "language tags".
31 other projects use a version of this, 17 of them edited.
Adopted by
Most recently taken up by
- martinbattaglia-commits/Claude-skillsedited, first seen Nov 16, 2026
- yotamwiesel/claude-skillsword for word, first seen Nov 16, 2026
- joaoguirunas/team-osedited, first seen Nov 15, 2026
- seranking/seo-skillstheir own version, first seen Nov 8, 2026
- alpit-patel/seo-aeo-geo-kitedited, first seen Nov 8, 2026
- zhtyyx/codex-seoedited, first seen Nov 1, 2026
Used with
Projects with it also use seo-agentic, seo-sxo and 10 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-sxo
Search Experience Optimization: reads Google SERPs backwards to detect page-type mismatches, derives user stories from search intent signals, and scores pages from multiple persona perspectives. Identifies why well-optimized pages fail to rank by analyzing what Google rewards for each keyword. Use when user says "SXO", "search experience", "page type mismatch", "SERP analysis", "user story", "persona scoring", "why isn't my page ranking", "intent mismatch", or "wireframe".
Also in 12 projects that use this
timruebenachSkillseo-google
Google SEO APIs: Search Console (Search Analytics, URL Inspection, Sitemaps), PageSpeed Insights v5, CrUX field data with 25-week history, Indexing API v3, and GA4 organic traffic. Provides real Google field data for Core Web Vitals, indexation status, search performance, and organic traffic trends. Use when user says "search console", "GSC", "PageSpeed", "CrUX", "field data", "indexing API", "GA4 organic", "URL inspection", "google api setup", "real CWV data", "impressions", "clicks", "CTR", "position data", "LCP", "INP", "CLS", "FCP", "TTFB", or "Lighthouse scores".
Also in 11 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
indranilbanerjeeSkillseo-drift
Compare two SEO exports (Search Console, two dates): gainers, losers, drift classes. \"what moved after the core update\"
Also in 11 projects that use this
mangollcSkillseo-local
Local SEO optimization: Google Business Profile post generation, 30-day posting calendars, NAP consistency checks, local citation audits, review response templates, local keywords.
Also in 14 projects that use this
- +6 more from timruebenach
Other versions31 projects use a version of this.
Word for word · 8
- coopersimson96/ai-content-system★ 17100% same
- 01clauding/claude-seo-skill★ 4100% same
- megastep/codex-skills★ 4100% same
- realwigu/claude-skills★ 4100% same
- get-proofpilot/claude-skills-catalog★ 1100% same
- hungphamwp/claude-skills★ 1100% same
- royaluniondesign-sys/claude-os★ 1100% same
- yotamwiesel/claude-skills★ 0100% same
Edited · 17
- AgriciDaniel/claude-seo★ 30k51% same
- zhtyyx/codex-seo★ 15251% same
- joaoguirunas/team-os★ 652% same
- avalonreset/legends-seo-dungeon★ 457% same
- alpit-patel/seo-aeo-geo-kit★ 250% same
- agrivisionai/claude-skills★ 169% same
- mahiunfiltered/claude-code-skills★ 169% same
- unknownking07/claude-skills★ 192% same
- ahmedaminsa/aljazeera360-mcp-server★ 058% same
- Biznomad/claude-skills★ 069% same
7 more not listed
Wrote their own version · 6
- seranking/seo-skills★ 201same name
- ZachArticulateV/designer-pro-and-seo★ 10same name
- oegeyilmaz9/seo-aeo-geo-ultimate★ 6same name
- amirjahfar1/automate-seo-with-claude★ 2same name
- david-corroy/skills-seo-geo★ 0same name
- DoddleHQ/doddle-seo-geo-skills★ 0same name
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.
- auditoria-localSkill
- consent-mode-v2-gtmSkill
- diseno-webSkill
- mejora-sistemaSkill
- n8n-code-javascriptSkill
- n8n-code-pythonSkill
- n8n-expression-syntaxSkill
- n8n-mcp-tools-expertSkill
- n8n-node-configurationSkill
- n8n-validation-expertSkill
- n8n-workflow-patternsSkill
- reelSkill
- seo-auditSkill
- seo-competitor-pagesSkill
- seo-contentSkill
- seo-geoSkill
- seo-imagesSkill
- seo-pageSkill
- seo-planSkill
- seo-programmaticSkill
- seo-schemaSkill
- seo-sitemapSkill
- seoSkill
- seo-technicalSkill
- shopify-audit-setupSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. 10 are common, 1 is distinctive, and 4 are very specific to this project.
10
Common
Most of the 23 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Common: line 19
Every page must include an hreflang tag pointing to itself
- Common: line 24
If page A links to page B with hreflang, page B must link back to page A
- Common: line 25
Every hreflang relationship must be bidirectional (A→B and B→A)
- Common: line 27
Check all language versions reference each other (full mesh)
- Common: line 32
Only one x-default per set of alternates
- Common: line 33
Must also have return tags from all other language versions
- Very specific: line 36
Must use ISO 639-1 two-letter codes (e.g., en, fr, de, ja)
- Very specific: line 52
If a page has rel=canonical pointing elsewhere, hreflang on that page is ignored
- Common: line 57
All URLs in an hreflang set must use the same protocol (HTTPS or HTTP)
- Common: line 59
After HTTPS migration, update all hreflang tags to HTTPS
- Distinctive: line 64
Verify both domains are verified in Google Search Console
- Very specific: line 94
Place in <head> section. Every page must include all alternates including itself.
- Common: line 124
Validate language codes: Verify all codes against ISO 639-1 and ISO 3166-1
- Common: line 125
Generate tags: Create hreflang tags for each page including self-referencing
- Very specific: line 156
Every <url> entry must include ALL language alternates (including itself)
“Common” is measured: kept by at least 6 in 10 of the 23 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
Hreflang & International SEO
Validate existing hreflang implementations or generate correct hreflang tags for multi-language and multi-region sites. Supports HTML, HTTP header, and XML sitemap implementations.
Validation Checks
1. Self-Referencing Tags
- Every page must include an hreflang tag pointing to itself
- The self-referencing URL must exactly match the page's canonical URL
- Missing self-referencing tags cause Google to ignore the entire hreflang set
2. Return Tags
- If page A links to page B with hreflang, page B must link back to page A
- Every hreflang relationship must be bidirectional (A→B and B→A)
- Missing return tags invalidate the hreflang signal for both pages
- Check all language versions reference each other (full mesh)
3. x-default Tag
- Required: designates the fallback page for unmatched languages/regions
- Typically points to the language selector page or English version
- Only one x-default per set of alternates
- Must also have return tags from all other language versions
4. Language Code Validation
- Must use ISO 639-1 two-letter codes (e.g.,
en,fr,de,ja) - Common errors:
enginstead ofen(ISO 639-2, not valid for hreflang)jpinstead ofja(incorrect code for Japanese)zhwithout region qualifier (ambiguous — usezh-Hansorzh-Hant)
5. Region Code Validation
- Optional region qualifier uses ISO 3166-1 Alpha-2 (e.g.,
en-US,en-GB,pt-BR) - Format:
language-REGION(lowercase language, uppercase region) - Common errors:
en-ukinstead ofen-GB(UK is not a valid ISO 3166-1 code)es-LA(Latin America is not a country — use specific countries)- Region without language prefix
6. Canonical URL Alignment
- Hreflang tags must only appear on canonical URLs
- If a page has
rel=canonicalpointing elsewhere, hreflang on that page is ignored - The canonical URL and hreflang URL must match exactly (including trailing slashes)
- Non-canonical pages should not be in any hreflang set
7. Protocol Consistency
- All URLs in an hreflang set must use the same protocol (HTTPS or HTTP)
- Mixed HTTP/HTTPS in hreflang sets causes validation failures
- After HTTPS migration, update all hreflang tags to HTTPS
8. Cross-Domain Support
- Hreflang works across different domains (e.g., example.com and example.de)
- Cross-domain hreflang requires return tags on both domains
- Verify both domains are verified in Google Search Console
- Sitemap-based implementation recommended for cross-domain setups
Common Mistakes
| Issue | Severity | Fix |
| Missing self-referencing tag | Critical | Add hreflang pointing to same page URL |
| Missing return tags (A→B but no B→A) | Critical | Add matching return tags on all alternates |
| Missing x-default | High | Add x-default pointing to fallback/selector page |
Invalid language code (e.g., eng) | High | Use ISO 639-1 two-letter codes |
Invalid region code (e.g., en-uk) | High | Use ISO 3166-1 Alpha-2 codes |
| Hreflang on non-canonical URL | High | Move hreflang to canonical URL only |
| HTTP/HTTPS mismatch in URLs | Medium | Standardize all URLs to HTTPS |
| Trailing slash inconsistency | Medium | Match canonical URL format exactly |
| Hreflang in both HTML and sitemap | Low | Choose one method — sitemap preferred for large sites |
| Language without region when needed | Low | Add region qualifier for geo-targeted content |
Implementation Methods
Method 1: HTML Link Tags
Best for: Sites with <50 language/region variants per page.
<link rel="alternate" hreflang="en-US" href="https://example.com/page" />
<link rel="alternate" hreflang="en-GB" href="https://example.co.uk/page" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
<link rel="alternate" hreflang="x-default" href="https://example.com/page" />Place in <head> section. Every page must include all alternates including itself.
Method 2: HTTP Headers
Best for: Non-HTML files (PDFs, documents).
Link: <https://example.com/page>; rel="alternate"; hreflang="en-US",
<https://example.com/fr/page>; rel="alternate"; hreflang="fr",
<https://example.com/page>; rel="alternate"; hreflang="x-default"Set via server configuration or CDN rules.
Method 3: XML Sitemap (Recommended for large sites)
Best for: Sites with many language variants, cross-domain setups, or 50+ pages.
See Hreflang Sitemap Generation section below.
Method Comparison
| Method | Best For | Pros | Cons |
| HTML link tags | Small sites (<50 variants) | Easy to implement, visible in source | Bloats <head>, hard to maintain at scale |
| HTTP headers | Non-HTML files | Works for PDFs, images | Complex server config, not visible in HTML |
| XML sitemap | Large sites, cross-domain | Scalable, centralized management | Not visible on page, requires sitemap maintenance |
Hreflang Generation
Process
- Detect languages: Scan site for language indicators (URL path, subdomain, TLD, HTML lang attribute)
- Map page equivalents: Match corresponding pages across languages/regions
- Validate language codes: Verify all codes against ISO 639-1 and ISO 3166-1
- Generate tags: Create hreflang tags for each page including self-referencing
- Verify return tags: Confirm all relationships are bidirectional
- Add x-default: Set fallback for each page set
- Output: Generate implementation code (HTML, HTTP headers, or sitemap XML)
Hreflang Sitemap Generation
Sitemap with Hreflang
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
xmlns:xhtml="http://www.w3.org/1999/xhtml">
<url>
<loc>https://example.com/page</loc>
<xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/page" />
<xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
<xhtml:link rel="alternate" hreflang="de" href="https://example.de/page" />
<xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" />
</url>
<url>
<loc>https://example.com/fr/page</loc>
<xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/page" />
<xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
<xhtml:link rel="alternate" hreflang="de" href="https://example.de/page" />
<xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" />
</url>
</urlset>Key rules:
- Include the
xmlns:xhtmlnamespace declaration - Every
<url>entry must include ALL language alternates (including itself) - Each alternate must appear as a separate
<url>entry with its own full set - Split at 50,000 URLs per sitemap file
Output
Hreflang Validation Report
Summary
- Total pages scanned: XX
- Language variants detected: XX
- Issues found: XX (Critical: X, High: X, Medium: X, Low: X)
Validation Results
| Language | URL | Self-Ref | Return Tags | x-default | Status |
| en-US | https://... | ✅ | ✅ | ✅ | ✅ |
| fr | https://... | ❌ | ⚠️ | ✅ | ❌ |
| de | https://... | ✅ | ❌ | ✅ | ❌ |
Generated Hreflang Tags
- HTML
<link>tags (if HTML method chosen) - HTTP header values (if header method chosen)
hreflang-sitemap.xml(if sitemap method chosen)
Recommendations
- Missing implementations to add
- Incorrect codes to fix
- Method migration suggestions (e.g., HTML → sitemap for scale)
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.

