International SEO and hreflang

Markdown delivery contract

Read markdown-delivery-contract.md for every task. Write a substantive .md document for every material work step and register its direct destination in the work index.md. For public-site work, apply the owner-required Markdown discovery profile across the full eligible inventory; preserve native standards and immutable evidence formats.

Lane outputs: locale-map.md; locale-verification.md (combine small related steps with stable section links). Map every HTML locale owner to its language-correct Markdown document and localized topic map. Preserve valid HTML/HTTP/XML hreflang where applicable. Markdown locale metadata is explanatory and does not replace hreflang.

Purpose

Validate reciprocal locale clusters and plan language/region targeting that reflects actual localized pages. This skill does not translate content, create markets, change canonicals, or deploy annotations.

Read references/locale-cluster-protocol.md before generating a repair plan.

Input gate

Require a URL-to-locale inventory, declared language/region intent, canonical URLs, current annotations or sitemap/header data, page accessibility, and ownership of each localized variant. Do not infer a locale from a URL slug, browser language, or translated sample alone.

Workflow

1. Model the cluster. Name the page purpose/entity, canonical URL for each actual locale variant, language/region code, content status, and optional x-default intent.
2. Validate the graph. Check self-reference, reciprocal links, canonical alignment, absolute/crawlable destination URLs, code syntax, redirects, indexability intent, and parity of the cluster. Record inaccessible URLs as limitations rather than guessing their markup.
3. Inspect reader fit. Verify that the destination truly serves the declared language/market and does not silently force a different locale, price, legal regime, or product availability.
4. Propose bounded repairs. State the exact source/destination pair, annotation delivery method, owner, test URLs, approval, verification, and rollback. Avoid mass templates until a representative cluster passes.
5. Verify after change. Re-crawl all cluster members, compare reciprocal annotations and canonicals, and monitor the relevant platform reports as observations—not guarantees.

Rules

• Use current official documentation for supported annotation methods and syntax; do not rely on copied country-code lists or stale error folklore.
• x-default is purposeful fallback behavior, not a required decoration.
• A hreflang annotation cannot make an untranslated page appropriate for a market, override legal/product availability, or guarantee geographic ranking.
• Do not use hreflang to solve duplicate, canonical, or automatic-redirect problems without examining those systems separately.
• Large cluster changes, canonical changes, redirects, and locale gating require an approved seo-action-plan with rollback.

Formal evidence handoff

When this work needs a cross-team, approval-ready plan, package evidence-bound findings as an immutable seo-findings.json bundle using the checked-out suite contract. Let <suite-root> mean ${CLAUDE_PLUGIN_ROOT} in Claude Code. In Codex, read .seo-suite-runtime.json beside this SKILL.md when present and use its suite_root value; otherwise use the absolute repository checkout. Keep every referenced capture/source below raw/, retain declined claims and limitations, and run python "<suite-root>/scripts/validate_seo_findings.py" validate-findings <bundle>/seo-findings.json --bundle <bundle>. Send only a passing bundle to seo-action-plan; otherwise label the handoff provisional.

Output

Return a cluster inventory, confirmed mismatches, unresolved access/data gaps, exact repair map, approval/owner, validation steps, and rollback. Use a pass/warn/fail status per check if useful, but never a single international-SEO score.