SkillAgentSearch skills...

seo-hreflang

Hreflang and international SEO audit, validation, and generation. Detects common mistakes, validates language/region codes, and generates correct hreflang implementations

Install / Use

npx skills add AgriciDaniel/claude-seo --skill seo-hreflang

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

97/100

Category

Marketing

Supported Platforms

Universal

Tags

Our assessment of seo-hreflang

seo-hreflang scores 97/100 on our quality scale, 33rd of 642 Marketing skills we index (top 6%).

Its SKILL.md is 13 KB long, well organised into 33 sections with 3 code examples: a thorough specification that gives an agent plenty to work with.

With 29,294 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
18/20
Description
15/15
Adoption
19/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated 2 days ago, so seo-hreflang is actively maintained.
  • Our last check on 2026-11-14 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-09-28. Automated pattern scan on 2026-09-28. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

seo-hreflang compared with similar skills

All 4 of these similar skills score higher than seo-hreflang; compare them before choosing.

SkillScoreStarsUpdatedFormat
seo-hreflang (this skill)by AgriciDaniel9729.3k2d agoSKILL.md
x402by browser-use100121.0k3d agoSKILL.md
algorithmic-artby anthropics100177.9k55d agoSKILL.md
pptxby anthropics100177.9k55d agoSKILL.md
designby nextlevelbuilder100149.0k6d agoSKILL.md

Frequently asked questions

How do I install seo-hreflang?
Run npx skills add AgriciDaniel/claude-seo --skill seo-hreflang. The install tabs above show the steps for each supported agent.
Which AI agents does seo-hreflang work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is seo-hreflang safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is seo-hreflang still maintained?
The repository was last updated 2 days ago, so seo-hreflang is actively maintained.

name: seo-hreflang description: > 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". user-invocable: true argument-hint: "[url]" license: MIT metadata: author: AgriciDaniel version: "2.4.0" category: seo

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

  • Recommended when a selector/fallback URL exists: 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)
  • An optional ISO 15924 script subtag is the documented, official mechanism for script: zh-Hant (Traditional) / zh-Hans (Simplified). Script may combine with a region, e.g. zh-Hans-US is valid (language + script + region).
  • Common errors:
    • eng instead of en (ISO 639-2, not valid for hreflang)
    • jp instead of ja (incorrect code for Japanese)
    • zh is valid but ambiguous for script-specific pages; prefer zh-Hans or zh-Hant when targeting a script

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)
  • A country code alone is invalid, you cannot specify a region without a language (Google's own bad example is be, which is actually the Belarusian language code, not Belgium).
  • Common errors:
    • en-uk instead of en-GB (UK is not a valid ISO 3166-1 region code)
    • EU / UN as a region (not valid ISO 3166-1 values)
    • es-LA (Latin America is not a country; use specific countries)
    • Region without language prefix

5b. Geo-targeting signal hierarchy

  • Practical locale-signal heuristic: ccTLD > hreflang annotations > server location/IP > addresses/language/currency/Business Profile. Do not present this as a confirmed Google ranking order. hreflang is a hint, not a directive. Google ignores locational meta tags and HTML geotargeting attributes.
  • The Search Console International Targeting report and the manual country-targeting setting were removed in 2022, do not recommend setting country targeting in GSC; hreflang is the remaining lever.

5c. Region-specific Search units (EEA, South Africa, Türkiye)

  • Google documents Search experiences that exist only in certain regions (documentation added 2026-09-08; https://developers.google.com/search/docs/appearance/aggregator-features):
    • EEA only: aggregator units and supplier units (hotels, flights, ground transportation, products, and since 2026-09-18 local businesses), the ecosystem carousel, and job-site features.
    • Türkiye: places-site features (hotels, local businesses).
    • South Africa: a badge and refinement chip for travel, products, car hire, food delivery and ground transportation.
    • Structured data carousels in all three, with different query types. Eligibility and participation are documented per unit; they are not ranking signals.
  • When a site serves those regions with hreflang variants, note in the report whether the business is an aggregator or a direct supplier and point to the regional documentation, so the client is not surprised by a different result layout in those markets.

6. Canonical URL Alignment

  • Hreflang tags must only appear on canonical URLs
  • If a page has rel=canonical pointing 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
  • Use Google Search Console verification for monitoring or cross-site sitemap submission when needed
  • 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 when fallback behavior is required | Medium | 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

  1. Detect languages: Scan site for language indicators (URL path, subdomain, TLD, HTML lang attribute)
  2. Map page equivalents: Match corresponding pages across languages/regions
  3. Validate language codes: Verify all codes against ISO 639-1 and ISO 3166-1
  4. Generate tags: Create hreflang tags for each page including self-referencing
  5. Verify return tags: Confirm all relationships are bidirectional
  6. Add x-default: Set fallback for each page set
  7. 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:xhtml namespace 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 whichever comes first: 50,000 URLs or 50MB uncompressed 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 to sitemap for scale)

Cultural Adaptation Assessment

When analyzing a multi-language site, go beyond technical hreflang validation to assess whether the content is culturally adapted for each target market.

Load references/cultural-profiles.md for pre-built profiles (DACH, Francophone, Hispanic, Japanese).

Assessment steps:

  1. Identify all language versions and their target markets
  2. Load the relevant cultural profile(s)
  3. Check CTAs match cultural expectations (direct vs indirect)
  4. Check trust signals are locale-appropriate (certifications, legal pages)
  5. Check for foreign brand references on localized pages
  6. Check number/date/currency formatting consistency
  7. Flag cultural adaptation issues as Medium severity

Output: Cultural Adaptation Score per language version (0-100) with specific findings.

Content Parity Audit

Command: /seo hreflang audit <directory-or-url>

Audit content parity across all language versions of a site or local content directory.

Load references/content-parity.md for the full parity matrix and scoring methodology.

What it checks:

  • Page existence across all declared languages
  • Section structure equivalence (H2/H3 count)
  • SEO element parity (title, meta, schema localization)
  • Word count ratio validation (DE should be 25-35% longer than EN, JA 10-25% shorter)
  • Freshness tracking (stale translations detected via timestamps)
  • Cultural marker scanning (foreign brands, wrong legal references, untranslated elements)

Output: Parity matrix table with per-page scores and prioritized action items.

Locale Format Validation

Load

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars29.3k
CategoryMarketing
Updated2d ago
Forks3.7k

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions
seo-hreflang — Universal Skill: Install & Safety Check | SkillAgent