Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AgricIDaniel/claude-seo/llms.txt

Use this file to discover all available pages before exploring further.

Claude SEO’s commerce and internationalization commands address two of the most technically demanding areas of modern SEO: getting product pages right for Google Shopping and AI-driven commerce surfaces, and building a correct hreflang implementation for multi-language or multi-region sites. /seo ecommerce was contributed by Matej Marjanovic (Pro Hub Challenge, v1.9.0); /seo hreflang enhancements were contributed by Chris Muller (Pro Hub Challenge, v1.9.0). Both were extended in v2 with new signal checks aligned to the January 2025 Quality Rater Guidelines and Google’s EU compliance requirements.

/seo ecommerce

Product schema validation, Google Shopping competitive intelligence, Amazon marketplace cross-reference, marketplace keyword gap analysis, and DataForSEO cost guardrails. Works fully without DataForSEO; marketplace data is additive.

/seo hreflang

Hreflang audit with eight validation checks (self-referencing, return tags, x-default, ISO codes, canonical alignment, protocol consistency), hreflang generation for HTML / HTTP header / XML sitemap, content parity audit, and cultural adaptation scoring.

​
/seo ecommerce <url>

/seo ecommerce covers four analysis areas: on-page product SEO, Google Shopping intelligence, Amazon marketplace cross-reference, and keyword gap analysis between organic and Shopping visibility. 
# Full e-commerce SEO analysis of a product page or store
/seo ecommerce https://shop.example.com/product/x

# Google Shopping competitive analysis for a keyword
/seo ecommerce products "wireless headphones"

# Keyword gap: organic vs Shopping visibility
/seo ecommerce gaps example.com

# Product schema validation and enhancement only
/seo ecommerce schema https://shop.example.com/product/x

​
Product schema validation

The skill validates Product schema against Google’s current requirements and scores completeness on a structured ladder:
Schema completenessScore
All required fields (name, image, description, brand, offers)50/100
+ aggregateRating65/100
+ sku / gtin13 / mpn75/100
+ shippingDetails (ShippingDetails with rate and delivery time)85/100
+ hasMerchantReturnPolicy (MerchantReturnPolicy with type and days)90/100
+ individual reviews (3+)100/100
The v2 Phase D schema validator also checks MemberProgram, EU energyEfficiencyClass, and ProductGroup variants — requirements that affect Google Merchant Center eligibility in the EU.

​
IPTC TrainedAlgorithmicMedia

For AI-generated product images, the skill checks for the DigitalSourceType: TrainedAlgorithmicMedia IPTC metadata label, now required by Google Merchant Center policy. This check surfaces through the seo-images integration layer and is reported alongside standard image optimization findings.

​
Marketplace intelligence

When the DataForSEO extension is installed, the skill runs Google Shopping and Amazon competitive analysis and produces a pricing intelligence report (min, max, median, P25/P75 distribution, price-to-rating correlation) and a seller landscape table (top 10 sellers by listing count, merchant rating distribution, free-shipping prevalence).
DataForSEO cost guardrails. Before every Merchant API call, the skill runs python3 scripts/dataforseo_costs.py check merchant_google_products_search. A needs_approval status shows the estimated cost and waits for confirmation. A blocked status stops execution entirely. Amazon endpoints are in the warn_endpoints set — they always require user approval. You can configure a per-request budget limit in the DataForSEO extension settings.

​
Keyword gap analysis

The gap report cross-references organic keyword rankings (from dataforseo_labs_google_ranked_keywords) against Google Shopping presence (from the Merchant API) for the same domain, producing four gap types:
Gap typeMeaningRecommended action
Organic OnlyRanks organically, no Shopping adsCreate Google Merchant Center feed for these keywords
Shopping OnlyShopping visible, weak organicCreate buying guides and comparison content
Both PresentVisible in both channelsOptimize: price consistency, enhanced schema
NeitherNo visibility in either channelLow priority unless high volume

​
/seo hreflang <url>

/seo hreflang audits, generates, and validates hreflang implementations across all three methods: HTML <link> tags, HTTP headers (for non-HTML files), and XML sitemap (recommended for sites with many language variants or cross-domain setups). 
# Full hreflang and i18n SEO audit
/seo hreflang https://example.com

# Content parity audit across language versions
/seo hreflang audit /path/to/content-directory

​
Eight validation checks

The skill runs eight checks in sequence. A failure in the self-referencing or return-tag checks invalidates the entire hreflang signal set for the affected pages:
  1. Self-referencing tags — Every page must include an hreflang tag pointing to itself; the URL must match the page’s canonical exactly.
  2. Return tags — If A→B, then B→A is mandatory. Missing return tags invalidate the signal for both pages.
  3. x-default tag — Required fallback for unmatched languages/regions. Only one x-default per set; must also have return tags from all other language versions.
  4. Language code validation — Must use ISO 639-1 two-letter codes. Common failures: eng instead of en, jp instead of ja, bare zh without a script qualifier (zh-Hans or zh-Hant).
  5. Region code validation — Must use ISO 3166-1 Alpha-2. Common failures: en-uk (should be en-GB), es-LA (Latin America is not a country code).
  6. Canonical URL alignment — Hreflang tags must only appear on canonical URLs. A page with rel=canonical pointing elsewhere will have its hreflang ignored.
  7. Protocol consistency — All URLs in a set must use the same protocol. Mixed HTTP/HTTPS causes validation failures.
  8. Cross-domain support — Cross-domain hreflang requires return tags on both domains and both domains verified in Google Search Console. XML sitemap implementation is recommended for cross-domain setups.

​
Common mistakes at a glance

IssueSeverity
Missing self-referencing tagCritical
Missing return tags (A→B but no B→A)Critical
Missing x-defaultHigh
Invalid language code (e.g., eng)High
Invalid region code (e.g., en-uk)High
Hreflang on non-canonical URLHigh
HTTP/HTTPS mismatch in URLsMedium
Trailing slash inconsistencyMedium
Hreflang in both HTML and sitemapLow

​
Hreflang generation

The skill generates production-ready hreflang output for all three implementation methods. For the XML sitemap method: 
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://example.com/page</loc>
    <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/page" />
    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
    <xhtml:link rel="alternate" hreflang="de" href="https://example.de/page" />
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" />
  </url>
</urlset>

​
v2 Phase F additions

Two Phase F (v2) additions extend the hreflang skill beyond tag validation:
  • Machine-translation QA flag — Per the January 2025 Quality Rater Guidelines update, the skill flags pages where content appears to have been machine-translated without post-editing. This is reported as a content quality issue rather than a technical one.
  • DMA consent-mode-v2 click-through diagnostic — For EU-targeted sites, the skill checks whether Google’s Consent Mode v2 is implemented correctly to maintain conversion modeling compliance under the Digital Markets Act.

​
Content parity audit

/seo hreflang audit checks that all declared language versions exist, have equivalent heading structure (H2/H3 count), matching SEO elements (title, meta, schema localization), appropriate word count ratios (German pages should be 25–35% longer than English; Japanese 10–25% shorter), and no stale translations. Foreign brand references on localized pages and untranslated elements are flagged as cultural adaptation issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us