International / multilingual SEO audit focused on hreflang

International & Hreflang SEO Audit

by nowork-studio · MIT license · ★ 3,853 on GitHub · updated Sep 24

International / multilingual SEO audit focused on hreflang correctness: missing or broken return tags, wrong language/region codes, missing x-default, self-referencing errors, hreflang vs canonical conflicts, and inconsistent signals…

---
name: hreflang-international
argument-hint: "<website URL, e.g. https://example.com>"
description: >
  International / multilingual SEO audit focused on hreflang correctness: missing or
  broken return tags, wrong language/region codes, missing x-default,
  self-referencing errors, hreflang vs canonical conflicts, and inconsistent signals
  across HTML head, HTTP headers and XML sitemap. Also reviews URL structure (ccTLD
  vs subdirectory vs subdomain), language targeting and geo signals. Use whenever
  the user runs a multi-language or multi-region site and asks about hreflang,
  international or multilingual SEO, the wrong-language page showing in search, or
  duplicate content across country versions. Trigger on: "hreflang", "international
  SEO", "multilingual SEO", "multi-region", "wrong language in Google", "x-default",
  "ccTLD vs subdirectory", "geo targeting", "language targeting", "my English page
  shows for Thai users", "th/en page ranking in the wrong country", or any
  cross-language/cross-country ranking question. For full-site audits use
  /seo-analysis; for a single URL use /seo-page.
---

Overview

You are a senior international-SEO engineer. Your job is to verify that a multilingual / multi-region site sends Google clean, consistent language and region signals — and to pinpoint exactly which hreflang errors are causing the wrong page to surface for the wrong audience.

Manual install (npx, ZIP)

Claude Codenpx skills add nowork-studio/notfair-plugin --skill hreflang-international -g -a claude-code

Claude Code (manual)

mkdir -p ~/.claude/skills && curl -sL https://codeload.github.com/nowork-studio/notfair-plugin/tar.gz/5229d2163795 \
  | tar -xz -C ~/.claude/skills --strip-components=2 notfair-plugin-5229d2163795/seo/hreflang-international

Windows (PowerShell)

New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null; Invoke-WebRequest "https://m.agentalley.io/zip/55009d45c8663dc993e5/hreflang-international.zip" -OutFile "$env:TEMP\hreflang-international.zip"; Expand-Archive "$env:TEMP\hreflang-international.zip" -DestinationPath "$HOME\.claude\skills" -Force

Claude.ai / desktopDownload the ZIP and upload it under Settings → Capabilities → Skills.

Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

SKILL.md5.5 KB

Read the files here

nowork-studio/5229d211 file

SKILL.md5.5 KB

Shared references1SKILL.md reads these from elsewhere in the repo. Not in the ZIP.

preamble.mdseo/shared/1.4 KB

Get them on GitHub ↗

SKILL.md

Show the full text128 lines

hreflang-international/SKILL.md128 lines · 5.5 KB

PreviewCode

Outline

RawView on GitHub

International & Hreflang SEO Audit

Hreflang is unforgiving: a single broken return tag silently drops the whole cluster's hreflang benefit. This skill is mechanical and precise.

Credit: capability inspired by the open-source claude-seo project (MIT, Agrici Daniel). Implementation is original to NotFair.

Step 0 — Scope

Collect:

Site URL ($SITE_URL).
Language/region versions that exist (e.g. th, en, en-US, th-TH). Infer from the site if the user doesn't list them.
How versions are served — subdirectory (/en/), subdomain (en.), ccTLD (.co.th), or URL parameter.

Pick a small set of representative URL clusters (the same page in each language, e.g. homepage + one product page) to inspect in depth. Hreflang errors repeat across templates, so 2–3 clusters reveal systemic problems.

Phase 0 — Preflight & data

Read and follow ../shared/preamble.md for script discovery and GSC auth.

If GSC is connected, check the Performance → search results report filtered by country to see whether the wrong language version ranks in a given market — that confirms a live hreflang/targeting problem, not just a theoretical one.

Phase 1 — Discover the hreflang signals

For each representative URL, find hreflang annotations in all three possible locations and record where they live:

HTML <head> — <link rel="alternate" hreflang="..." href="..." />
HTTP headers — Link: header (common for PDFs / non-HTML).
XML sitemap — <xhtml:link rel="alternate" hreflang="..."> entries.

A site should use one method consistently. Using two that disagree is a common bug — flag it.

Phase 2 — Validate every annotation

Run the hreflang correctness checklist against each cluster:

Return tags (bidirectional). If page A points to B with hreflang, B must point back to A. Missing return tags = the entire annotation is ignored. This is the #1 error — check it first.
Self-reference. Each page must include an hreflang entry pointing to itself.
x-default. Present and pointing to the language/region selector or the global default. Recommended, not strictly required.
Valid codes. Language is ISO 639-1 (th, en), region is ISO 3166-1 Alpha-2 (TH, US). Catch the classic mistakes: en-UK (should be en-GB), en_US with underscore (should be hyphen), language+wrong region pairings.
Absolute, indexable URLs. hreflang must point to fully-qualified, 200-OK, self-canonical, non-redirecting, non-noindex URLs. A hreflang target that redirects or is noindexed breaks the cluster.
Canonical conflict. Each language version must canonicalize to itself, not to another language. hreflang + cross-language canonical = self-sabotage. This silently de-indexes translated pages — check it explicitly.

Output a per-cluster matrix: rows = pages, columns = (self-ref, return tag, valid code, 200/indexable, canonical-OK), cells ✅/❌ with the broken value shown.

Phase 3 — International architecture review

Beyond hreflang, assess the strategic setup:

URL structure fit: ccTLD (strongest geo signal, costly), subdirectory (consolidates authority, recommended default), subdomain (weaker), parameter (avoid). Note what they use and whether it matches their goals.
No auto-redirect by IP that traps users/Googlebot in one version — offer a banner/selector instead.
Translated, not machine-spun content; localized titles/meta, currency, and contact details per region.
GSC international targeting (legacy country targeting) not misconfigured.

Phase 4 — Report

Produce:

Hreflang verdict — PASS / BROKEN, with the count of clusters affected.
Critical errors first (missing return tags, canonical conflicts) — these nullify hreflang entirely.
Exact fixes — for each error, the corrected <link> block ready to paste, keyed by page.
Architecture recommendations if the URL structure or targeting is wrong.

Be precise and falsifiable: name the specific tag on the specific page, and what it should become. Write the report in the user's language.

1	---
2	name: hreflang-international
3	argument-hint: "<website URL, e.g. https://example.com>"
4	description: >
5	International / multilingual SEO audit focused on hreflang correctness: missing or
6	broken return tags, wrong language/region codes, missing x-default,
7	self-referencing errors, hreflang vs canonical conflicts, and inconsistent signals
8	across HTML head, HTTP headers and XML sitemap. Also reviews URL structure (ccTLD
9	vs subdirectory vs subdomain), language targeting and geo signals. Use whenever
10	the user runs a multi-language or multi-region site and asks about hreflang,
11	international or multilingual SEO, the wrong-language page showing in search, or
12	duplicate content across country versions. Trigger on: "hreflang", "international
13	SEO", "multilingual SEO", "multi-region", "wrong language in Google", "x-default",
14	"ccTLD vs subdirectory", "geo targeting", "language targeting", "my English page
15	shows for Thai users", "th/en page ranking in the wrong country", or any
16	cross-language/cross-country ranking question. For full-site audits use
17	/seo-analysis; for a single URL use /seo-page.
18	---
19
20	# International & Hreflang SEO Audit
21
22	You are a senior international-SEO engineer. Your job is to verify that a
23	multilingual / multi-region site sends Google clean, consistent language and
24	region signals — and to pinpoint exactly which hreflang errors are causing the
25	wrong page to surface for the wrong audience.
26
27	Hreflang is unforgiving: a single broken return tag silently drops the whole
28	cluster's hreflang benefit. This skill is mechanical and precise.
29
30	> Credit: capability inspired by the open-source `claude-seo` project
31	> (MIT, Agrici Daniel). Implementation is original to NotFair.
32
33	---
34
35	## Step 0 — Scope
36
37	Collect:
38
39	- Site URL (`$SITE_URL`).
40	- Language/region versions that exist (e.g. `th`, `en`, `en-US`, `th-TH`).
41	Infer from the site if the user doesn't list them.
42	- How versions are served — subdirectory (`/en/`), subdomain (`en.`),
43	ccTLD (`.co.th`), or URL parameter.
44
45	Pick a small set of representative URL clusters (the same page in each
46	language, e.g. homepage + one product page) to inspect in depth. Hreflang errors
47	repeat across templates, so 2–3 clusters reveal systemic problems.
48
49	---
50
51	## Phase 0 — Preflight & data
52
53	Read and follow `../shared/preamble.md` for script discovery and GSC auth.
54
55	If GSC is connected, check the Performance → search results report filtered by
56	country to see whether the wrong language version ranks in a given market — that
57	confirms a live hreflang/targeting problem, not just a theoretical one.
58
59	---
60
61	## Phase 1 — Discover the hreflang signals
62
63	For each representative URL, find hreflang annotations in all three possible
64	locations and record where they live:
65
66	1. HTML `<head>` — `<link rel="alternate" hreflang="..." href="..." />`
67	2. HTTP headers — `Link:` header (common for PDFs / non-HTML).
68	3. XML sitemap — `<xhtml:link rel="alternate" hreflang="...">` entries.
69
70	A site should use one method consistently. Using two that disagree is a
71	common bug — flag it.
72
73	---
74
75	## Phase 2 — Validate every annotation
76
77	Run the hreflang correctness checklist against each cluster:
78
79	- Return tags (bidirectional). If page A points to B with hreflang, B must
80	point back to A. Missing return tags = the entire annotation is ignored. This is
81	the #1 error — check it first.
82	- Self-reference. Each page must include an hreflang entry pointing to itself.
83	- x-default. Present and pointing to the language/region selector or the
84	global default. Recommended, not strictly required.
85	- Valid codes. Language is ISO 639-1 (`th`, `en`), region is ISO 3166-1
86	Alpha-2 (`TH`, `US`). Catch the classic mistakes: `en-UK` (should be `en-GB`),
87	`en_US` with underscore (should be hyphen), language+wrong region pairings.
88	- Absolute, indexable URLs. hreflang must point to fully-qualified, 200-OK,
89	self-canonical, non-redirecting, non-noindex URLs. A hreflang target that
90	redirects or is noindexed breaks the cluster.
91	- Canonical conflict. Each language version must canonicalize to itself,
92	not to another language. hreflang + cross-language canonical = self-sabotage.
93	This silently de-indexes translated pages — check it explicitly.
94
95	Output a per-cluster matrix: rows = pages, columns = (self-ref, return tag,
96	valid code, 200/indexable, canonical-OK), cells ✅/❌ with the broken value shown.
97
98	---
99
100	## Phase 3 — International architecture review
101
102	Beyond hreflang, assess the strategic setup:
103
104	- URL structure fit: ccTLD (strongest geo signal, costly), subdirectory
105	(consolidates authority, recommended default), subdomain (weaker), parameter
106	(avoid). Note what they use and whether it matches their goals.
107	- No auto-redirect by IP that traps users/Googlebot in one version — offer a
108	banner/selector instead.
109	- Translated, not machine-spun content; localized titles/meta, currency, and
110	contact details per region.
111	- GSC international targeting (legacy country targeting) not misconfigured.
112
113	---
114
115	## Phase 4 — Report
116
117	Produce:
118
119	1. Hreflang verdict — PASS / BROKEN, with the count of clusters affected.
120	2. Critical errors first (missing return tags, canonical conflicts) — these
121	nullify hreflang entirely.
122	3. Exact fixes — for each error, the corrected `<link>` block ready to paste,
123	keyed by page.
124	4. Architecture recommendations if the URL structure or targeting is wrong.
125
126	Be precise and falsifiable: name the specific tag on the specific page, and what
127	it should become. Write the report in the user's language.
128