Skill
audit
Audit a website or web codebase for SEO and AI-search (GEO/AEO) — produces two independent 0-100 scores (Search SEO + AI Visibility) plus a prioritized,…
@hainrixzView SkillMarketing
Skill
/seo-international
Audit and generate hreflang annotations for multilingual sites — check reciprocity, BCP-47 validity, self-reference, x-default, hreflang/canonical conflicts, and <html lang> agreement, and emit reciprocal hreflang link sets. Module M20 (conditional). Feeds the Search SEO score.
Install
$ npx -y skills add Hainrixz/claude-seo-ai --skill seo-international --agent claude-codeHow it fires
How this skill gets triggered: by you, by Claude, or both.
- Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
- You can call itInvoke it directly when you want it.
- Slash command
/seo-international
Context preview
The summary Claude sees to decide when to auto-load this skill.
Audit and generate hreflang annotations for multilingual sites — check reciprocity, BCP-47 validity, self-reference, x-default, hreflang/canonical conflicts, and <html lang> agreement, and emit reciprocal hreflang link sets. Module M20 (conditional). Feeds the Search SEO score.
SKILL.md
seo-international.SKILL.mdname: seo-international
description: Audit and generate hreflang annotations for multilingual sites — check reciprocity, BCP-47 validity, self-reference, x-default, hreflang/canonical conflicts, and <html lang> agreement, and emit reciprocal hreflang link sets. Module M20 (conditional). Feeds the Search SEO score.
allowed-tools: Read, Grep, Glob, WebFetch, Bash
seo-international (M20)
hreflang tells search engines which language/region URL to serve. This module is **conditional**: it only runs when seo-vertical-detect flags a multilingual site (multiple `lang`/locale URLs, language switcher, or existing hreflang). On monolingual sites every finding is `not_applicable` at severity 0. Schema-type concerns defer to `references/schema-tier1.md`; this module owns link-level localization only.
Inputs
Work from the PageSnapshot named in your dispatch envelope: read `parsed` from `<run_dir>/pages/<slug>.json` (`hreflang[]`, `canonicals[]`, `<html lang>` in `parsed`) plus `headers.link` and the sibling pages under `<run_dir>/pages/` for reciprocity; Grep `pages/<slug>.html` for verbatim evidence; site artifacts live in `<run_dir>/site/{robots.json,sitemaps.json,discovery.json}`. Deterministic findings already emitted by `audit.mjs` are listed in `<run_dir>/findings.deterministic.json` — do not re-emit those ids; add model-judged findings only. If invoked directly with a URL/path and no snapshot exists, first run `node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs"` and use the printed snapshot path.
Audits
Working from the PageSnapshot (`parsed_rendered` when `render.used` is not `none`, else `parsed`). Read hreflang from `<link rel="alternate" hreflang="...">` in `<head>` (also accept HTTP `Link:` headers / sitemap `xhtml:link` when present): 1. **Reciprocity** — if page A declares an alternate B, B must declare A back. One-way hreflang is ignored by Google. 2. **BCP-47 validity** — each `hreflang` value is a valid language (`en`) or language-region (`en-GB`, `pt-BR`) tag; region is ISO-3166-1 alpha-2, not a country-of-language guess (`en-UK` is invalid; use `en-GB`). 3. **Self-reference** — the page lists itself in its own hreflang set. 4. **x-default** — at least one `hreflang="x-default"` for the language-selector / fallback URL. 5. **hreflang↔canonical conflict** — an hreflang URL must be self-canonical; pointing hreflang at a URL whose `rel=canonical` is a *different* page neutralizes the cluster (cross-check M2/seo-indexability). 6. **`<html lang>` agreement** — the document `lang` attribute matches the locale this URL targets in its own hreflang entry.
Fixes
- **AUTO** (`fixable: auto`): when the locale→URL map is **known** (supplied by the user, a sitemap, or discovered alternates), generate a complete reciprocal hreflang link set — every locale + a single `x-default` — as a `<head>` diff for `fix`. Additive and deterministic.
- **PROPOSED** (`fixable: proposed`): a partial set inferred from discovered alternates that needs the user to confirm the locale map before write.
- **ADVISORY** (`fixable: advisory`): "this looks multilingual but no locale map exists" — never written by the tool.
- **Never fabricate** locales, region codes, or alternate URLs. If the map is incomplete, leave a clearly-marked `TODO(locale)` placeholder and ask the user.
Verification
- Offline: `node "${CLAUDE_PLUGIN_ROOT}/scripts/hreflang-check.mjs" --snapshot <pages/<slug>.json>` (or `--url <u>` / `--file <path>`) — parses the alternate set from the `<link>` tags **and** the HTTP `Link` header (`entries`, `header_entries`), validates BCP-47 tags (`invalid_bcp47`), and reports `has_x_default`, `self_referenced`, `duplicate_langs` and the canonical-vs-hreflang conflict. Reciprocity is **not** in this mode: it needs `--url <u> --deep [--budget 25] [--ua <preset>]`, which fetches each declared alternate.
- Reciprocity requires fetching each declared alternate; when those URLs (or a sitemap tier) are unavailable, status is `needs_api`, **never** a false `pass`.
Findings
Findings conform to `schema/finding.schema.json`; axis `search`. On a monolingual site every id is `not_applicable` at severity 0. **Severity policy**: 5 is reserved for catastrophic, eligibility-killing facts at site/template scope; 4 major · 3 moderate · 2 minor · 1 cosmetic · 0 informational — and only an `established` severity-5 `fail` in an active category can cap a score (`references/scoring-model.md`).
- `M20.hreflang.missing_reciprocal` — the page declares `hreflang="de-DE"` for a URL that does not point back; Google ignores one-way annotations, so the cluster does not form (`fail`, severity 4, `fixable: proposed`, confidence `established`). `evidence.observed` quotes the one-way `<link>`.
- `M20.hreflang.invalid_bcp47` — e.g. `hreflang="en-UK"` (`fail`, severity **3**, `fixable: auto`, confidence `established`; recommend `en-GB`). One bad value invalidates that entry, not the whole set.
- `M20.hreflang.missing_self` — the page is absent from its own alternate set (`fail`, severity 3, `fixable: auto`, confidence `established`).
- `M20.hreflang.canonical_conflict` — an hreflang URL whose `rel=canonical` points at a different page, which neutralizes the cluster (`fail`, severity 4, `fixable: proposed`, confidence `established`; cross-check M2).
- `M20.hreflang.missing_xdefault` — the cluster has no `x-default` fallback (`warn`, severity **2**, `fixable: auto`, confidence `directional` — `x-default` is recommended, not required, and its absence degrades selector routing rather than breaking the cluster).
- `M20.lang.mismatch` — `<html lang>` disagrees with the locale this URL claims in its own hreflang entry (`warn`, severity 2, `fixable: auto`, confidence `directional`).
- `M20.hreflang.not_applicable` — monolingual site (`not_applicable`, severity 0).
**Platform-conditional ids.** This module also emits 1 id that fires only when `profile.json` names the platform (`shopify`)
Read more
name: seo-international description: Audit and generate hreflang annotations for multilingual sites — check reciprocity, BCP-47 validity, self-reference, x-default, hreflang/canonical conflicts, and <html lang> agreement, and emit reciprocal hreflang link sets. Module M20 (conditional). Feeds the Search SEO score. allowed-tools: Read, Grep, Glob, WebFetch, Bash
seo-international (M20)
hreflang tells search engines which language/region URL to serve. This module is **conditional**: it only runs when seo-vertical-detect flags a multilingual site (multiple `lang`/locale URLs, language switcher, or existing hreflang). On monolingual sites every finding is `not_applicable` at severity 0. Schema-type concerns defer to `references/schema-tier1.md`; this module owns link-level localization only.
Inputs
Work from the PageSnapshot named in your dispatch envelope: read `parsed` from `<run_dir>/pages/<slug>.json` (`hreflang[]`, `canonicals[]`, `<html lang>` in `parsed`) plus `headers.link` and the sibling pages under `<run_dir>/pages/` for reciprocity; Grep `pages/<slug>.html` for verbatim evidence; site artifacts live in `<run_dir>/site/{robots.json,sitemaps.json,discovery.json}`. Deterministic findings already emitted by `audit.mjs` are listed in `<run_dir>/findings.deterministic.json` — do not re-emit those ids; add model-judged findings only. If invoked directly with a URL/path and no snapshot exists, first run `node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs"` and use the printed snapshot path.
Audits
Working from the PageSnapshot (`parsed_rendered` when `render.used` is not `none`, else `parsed`). Read hreflang from `<link rel="alternate" hreflang="...">` in `<head>` (also accept HTTP `Link:` headers / sitemap `xhtml:link` when present): 1. **Reciprocity** — if page A declares an alternate B, B must declare A back. One-way hreflang is ignored by Google. 2. **BCP-47 validity** — each `hreflang` value is a valid language (`en`) or language-region (`en-GB`, `pt-BR`) tag; region is ISO-3166-1 alpha-2, not a country-of-language guess (`en-UK` is invalid; use `en-GB`). 3. **Self-reference** — the page lists itself in its own hreflang set. 4. **x-default** — at least one `hreflang="x-default"` for the language-selector / fallback URL. 5. **hreflang↔canonical conflict** — an hreflang URL must be self-canonical; pointing hreflang at a URL whose `rel=canonical` is a *different* page neutralizes the cluster (cross-check M2/seo-indexability). 6. **`<html lang>` agreement** — the document `lang` attribute matches the locale this URL targets in its own hreflang entry.
Fixes
- **AUTO** (`fixable: auto`): when the locale→URL map is **known** (supplied by the user, a sitemap, or discovered alternates), generate a complete reciprocal hreflang link set — every locale + a single `x-default` — as a `<head>` diff for `fix`. Additive and deterministic.
- **PROPOSED** (`fixable: proposed`): a partial set inferred from discovered alternates that needs the user to confirm the locale map before write.
- **ADVISORY** (`fixable: advisory`): "this looks multilingual but no locale map exists" — never written by the tool.
- **Never fabricate** locales, region codes, or alternate URLs. If the map is incomplete, leave a clearly-marked `TODO(locale)` placeholder and ask the user.
Verification
- Offline: `node "${CLAUDE_PLUGIN_ROOT}/scripts/hreflang-check.mjs" --snapshot <pages/<slug>.json>` (or `--url <u>` / `--file <path>`) — parses the alternate set from the `<link>` tags **and** the HTTP `Link` header (`entries`, `header_entries`), validates BCP-47 tags (`invalid_bcp47`), and reports `has_x_default`, `self_referenced`, `duplicate_langs` and the canonical-vs-hreflang conflict. Reciprocity is **not** in this mode: it needs `--url <u> --deep [--budget 25] [--ua <preset>]`, which fetches each declared alternate.
- Reciprocity requires fetching each declared alternate; when those URLs (or a sitemap tier) are unavailable, status is `needs_api`, **never** a false `pass`.
Findings
Findings conform to `schema/finding.schema.json`; axis `search`. On a monolingual site every id is `not_applicable` at severity 0. **Severity policy**: 5 is reserved for catastrophic, eligibility-killing facts at site/template scope; 4 major · 3 moderate · 2 minor · 1 cosmetic · 0 informational — and only an `established` severity-5 `fail` in an active category can cap a score (`references/scoring-model.md`).
- `M20.hreflang.missing_reciprocal` — the page declares `hreflang="de-DE"` for a URL that does not point back; Google ignores one-way annotations, so the cluster does not form (`fail`, severity 4, `fixable: proposed`, confidence `established`). `evidence.observed` quotes the one-way `<link>`.
- `M20.hreflang.invalid_bcp47` — e.g. `hreflang="en-UK"` (`fail`, severity **3**, `fixable: auto`, confidence `established`; recommend `en-GB`). One bad value invalidates that entry, not the whole set.
- `M20.hreflang.missing_self` — the page is absent from its own alternate set (`fail`, severity 3, `fixable: auto`, confidence `established`).
- `M20.hreflang.canonical_conflict` — an hreflang URL whose `rel=canonical` points at a different page, which neutralizes the cluster (`fail`, severity 4, `fixable: proposed`, confidence `established`; cross-check M2).
- `M20.hreflang.missing_xdefault` — the cluster has no `x-default` fallback (`warn`, severity **2**, `fixable: auto`, confidence `directional` — `x-default` is recommended, not required, and its absence degrades selector routing rather than breaking the cluster).
- `M20.lang.mismatch` — `<html lang>` disagrees with the locale this URL claims in its own hreflang entry (`warn`, severity 2, `fixable: auto`, confidence `directional`).
- `M20.hreflang.not_applicable` — monolingual site (`not_applicable`, severity 0).
**Platform-conditional ids.** This module also emits 1 id that fires only when `profile.json` names the platform (`shopify`)
Ships withclaude-seo-ai
The SEO + AI-search (GEO/AEO) optimization toolkit for Claude Code — two-score audit + opt-in fixer. Built for 2026-2027.
Get the whole plugin
Stats
61
Stars
5
Forks
Active
Maintenance
JavaScript
Language
MIT
License
8d ago
Last commit
3mo ago
Created
Repo: Hainrixz/claude-seo-ai
Other skills on claude-seo-ai.
@hainrixzView SkillSkill
compare
Compare a site against its own baseline, against a staging deployment, against up to four competitors, or against the pages that already answer a query…
@hainrixzView SkillSkill
fix
Opt-in fixer (the /claude-seo-ai:fix command). Applies the safe, deterministic SEO/AI-search fixes from a persisted audit to the user's site — meta…
@hainrixzView SkillSkill
geo
Analyze and score only a page's AI-search visibility (GEO/AEO) — answer extractability, fact density, AI-crawler access and Google AI-feature snippet…
@hainrixzView SkillSkill
score
Recompute and display the two scores (Search SEO + AI Visibility) from a persisted audit run, without re-crawling. Use to re-show or refresh the scores after…
@hainrixzView SkillSkill
seo-agent-readiness
Audit how well a page can be operated by AI agents and agentic browsers — semantic interactive controls (<button>/<a href> instead of div/span click handlers),…
@hainrixzView Skill