Claude Cursor Skill

hreflang-international

International / multilingual SEO audit focused on hreflang correctness. Detects and diagnoses the most common (and ranking-damaging) hreflang mistakes: missing or broken return tags, wrong language/region codes, missing x-default, self-referencing errors, conflicts between hrefla

LLM Mart · 0 points · 23 views 0 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download nowork-studio-notfair-plugin-seo_hreflang-international-adf7601.zip · 2 KB
nowork-studio/notfair-plugin 3849 495 forks MIT Updated 1d ago
Part of nowork-studio/notfair-plugin — 88 skills

Install

skills CLI npx skills add https://github.com/nowork-studio/notfair-plugin/tree/main/seo/hreflang-international
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install nowork-studio-notfair-plugin@llmmart
Git git clone https://github.com/nowork-studio/notfair-plugin.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole nowork-studio/notfair-plugin collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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-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:

  1. HTML <head> — <link rel="alternate" hreflang="..." href="..." />
  2. HTTP headers — Link: header (common for PDFs / non-HTML).
  3. 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:

  1. Hreflang verdict — PASS / BROKEN, with the count of clusters affected.
  2. Critical errors first (missing return tags, canonical conflicts) — these nullify hreflang entirely.
  3. Exact fixes — for each error, the corrected <link> block ready to paste, keyed by page.
  4. 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.

Files (notfair-plugin)
  • SKILL.md 5.7 KB 
    ---
name: hreflang-international
argument-hint: "<website URL, e.g. https://example.com>"
description: >
  International / multilingual SEO audit focused on hreflang correctness. Detects
  and diagnoses the most common (and ranking-damaging) hreflang mistakes: missing
  or broken return tags, wrong language/region codes, missing x-default,
  self-referencing errors, conflicts between hreflang and canonical, and
  inconsistent signals across HTML head / HTTP headers / XML sitemap. Also reviews
  the broader international setup — URL structure (ccTLD vs subdirectory vs
  subdomain), language targeting, and geo signals. Use this skill whenever the
  user runs a multi-language or multi-region site and asks about hreflang,
  international SEO, multilingual SEO, the wrong-language page showing in search,
  duplicate-content across country versions, or "th/en page ranking in the wrong
  country". 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",
  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-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:

1. **HTML `<head>`** — `<link rel="alternate" hreflang="..." href="..." />`
2. **HTTP headers** — `Link:` header (common for PDFs / non-HTML).
3. **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:

1. **Hreflang verdict** — PASS / BROKEN, with the count of clusters affected.
2. **Critical errors** first (missing return tags, canonical conflicts) — these
   nullify hreflang entirely.
3. **Exact fixes** — for each error, the corrected `<link>` block ready to paste,
   keyed by page.
4. **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.

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.

Related

Claude Prompt
Tighten-my-prose editing prompt
Claude Skill
Adversarial code-review skill for Claude
Claude Workflow
Deep-research workflow (fan-out + verify)
Claude Skill
Conventional-commit writer for Claude