International & Hreflang SEO Audit
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.
How to use it
Claude Code
- Run the line below. It pulls the whole folder into
~/.claude/skills/hreflang-international. - Describe your job in plain words. Claude Code follows the skill from there.
Claude Code — installs the whole folder, not just SKILL.md
npx degit nowork-studio/notfair-plugin/seo/hreflang-international#main ~/.claude/skills/hreflang-internationalFor one project only, change the path to .claude/skills/hreflang-international.
Claude (web or desktop app)
- On this page open ⋯ → Download .md.
- Save it as SKILL.md in a folder, zip the folder, then Customize → Skills → + → Create skill → Upload a skill.
- Pick the file and Save. Claude shows the name and description and runs a security scan.
- Check the skill is switched on.
- Start a new chat and describe your job in plain words. The AI follows the skill from there.
ChatGPT or another app
- ChatGPT: make a Project and paste it into Instructions.
- Neither? Paste it at the top of a new chat — it works for that chat.
Not working?
- Check which app you pasted it into — the steps above name the right one.
- Some skills need the paid tier of Claude or ChatGPT.
Paste into Claude, ChatGPT or Cursor.
Source of International & Hreflang SEO Audit
Show the full text128 lines
| name | argument-hint | description |
|---|---|---|
| hreflang-international | <website URL, e.g. https://example.com> | > 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. |
International & Hreflang SEO Audit
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.
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-seoproject (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 been-GB),en_USwith 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 | **HTML `<head>`** — `<link rel="alternate" hreflang="..." href="..." />` |
| 67 | **HTTP headers** — `Link:` header (common for PDFs / non-HTML). |
| 68 | **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 | **Hreflang verdict** — PASS / BROKEN, with the count of clusters affected. |
| 120 | **Critical errors** first (missing return tags, canonical conflicts) — these |
| 121 | nullify hreflang entirely. |
| 122 | **Exact fixes** — for each error, the corrected `<link>` block ready to paste, |
| 123 | keyed by page. |
| 124 | **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 |
Discussion
Backlink Profile AnalysisBacklink profile analysis: referring domains, anchor text distribution, toxic link detection, competitor gap analysis. Works with free APIs (Moz, Bing Webmaster, Common Crawl) and DataForSEO extension. Use when user says backlinks, link profile, referring domains, anchor text, toxic links, link gap, link building, disavow, or backlink audit./setup-cmsConnect a CMS to notfair SEO tools. Guides users through configuring WordPress, Strapi, Contentful, or Ghost — tests the connection, and writes credentials to .env.local. Once set up, seo-analysis automatically cross- references CMS content against Google Search Console data. Use whenever the user says "connect my CMS", "set up WordPress", "configure Strapi", "add Contentful", "connect Ghost", or "CMS setup". Also trigger if the user asks why no CMS data appears in a seo-analysis report.Core Web Vitals optimizationOptimize Core Web Vitals (LCP, INP, CLS) for better page experience using field and lab evidence. Use when asked to "improve Core Web Vitals", "fix LCP", "reduce CLS", "optimize INP", "page experience optimization", or "fix layout shifts".Claude opus as SEO auditorAct as Claude Opus, an expert SEO auditor, analyzing and optimizing websites for improved search engine performance.
Browse more free Claude skills or everything in Marketing.