What it does. E-commerce SEO analysis: Google Shopping visibility, Amazon marketplace intelligence, product schema validation, competitor pricing analysis, and marketplace keyword gaps. Combines on-page product SEO with marketplace data from DataForSEO Merchant API. Use when user says "ecommerce SEO", "product SEO", "Google Shopping", "marketplace SEO", "product schema", "Amazon SEO", "product listings", "shopping ads", or "merchant SEO". Part of seo skill (claude-seo: 25 sub-skills, 18 sub-agents) (AgriciDaniel/claude-seo).

Upstream	AgriciDaniel/claude-seo
Skill file	skills/seo-ecommerce/SKILL.md
License	MIT
Author	Daniel Agrici
Fetched	2026-09-10

Install

• Claude Code: /plugin marketplace add AgriciDaniel/claude-seo; other agents: npx skills add AgriciDaniel/claude-seo --skill seo-ecommerce.
• Raw file: curl -sL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/HEAD/skills/seo-ecommerce/SKILL.md

SKILL.md (verbatim)

name: seo-ecommerce
description: >
  E-commerce SEO analysis: Google Shopping visibility, Amazon marketplace
  intelligence, product schema validation, competitor pricing analysis, and
  marketplace keyword gaps. Combines on-page product SEO with marketplace data
  from DataForSEO Merchant API. Use when user says "ecommerce SEO", "product SEO",
  "Google Shopping", "marketplace SEO", "product schema", "Amazon SEO",
  "product listings", "shopping ads", or "merchant SEO".
user-invocable: true
argument-hint: "<url or keyword>"
license: MIT
compatibility: "Enhanced with DataForSEO Merchant API (optional)"
metadata:
  author: AgriciDaniel
  original_author: "Matej Marjanovic (Pro Hub Challenge)"
  version: "2.2.6"
  category: seo

E-commerce SEO Analysis

Comprehensive product page optimization, marketplace intelligence, and competitive pricing analysis. Works standalone (on-page + schema) and with DataForSEO Merchant API for live Google Shopping and Amazon data.

Commands

Command	Purpose	DataForSEO?
/seo ecommerce <url>	Full e-commerce SEO analysis of a product page or store	Optional
/seo ecommerce products <keyword>	Google Shopping competitive analysis	Required
/seo ecommerce gaps <domain>	Keyword gap: organic vs Shopping visibility	Required
/seo ecommerce schema <url>	Product schema validation and enhancement	No

---

1. Product Page Analysis (No DataForSEO Needed)

Fetch and parse any product page for on-page SEO quality.

Workflow

1. "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run render_page.py <url> --mode auto → raw/rendered HTML
2. "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run parse_html.py --url <url>   → SEO elements
3. Analyze product-specific signals (below)

Product SEO Checklist

Title Tag

• Contains primary product keyword
• Includes brand name
• Under 60 characters (no truncation in SERPs)
• Format: [Product Name] - [Key Feature] | [Brand]

Meta Description

• Contains product keyword + benefit
• Includes price or "from $XX" (triggers rich snippet interest)
• Call-to-action present (Shop now, Buy, Free shipping)
• Under 155 characters

Heading Structure

• Single H1 matching primary product name
• H2s for: Features, Specifications, Reviews, Related Products
• No duplicate H1 tags across product variants

Product Images

• Alt text includes product name + distinguishing feature
• File names are descriptive (not IMG_001.jpg)
• WebP format served (with JPEG fallback)
• At least 3 images per product (hero, detail, lifestyle)
• Image dimensions >= 800px for Google Shopping eligibility
• Lazy loading on below-fold images only

Internal Linking

• Breadcrumb navigation: Home > Category > Subcategory > Product
• Related products section (cross-sell / upsell)
• Link back to category page with keyword-rich anchor
• Reviews section links to full review page (if separate)

Content Quality

• Unique product description (not manufacturer copy-paste)
• Word count >= 200 for product description body
• Specs table present (not just prose)
• User reviews on-page (UGC signals)

Scoring

Category	Weight	Criteria
Schema completeness	25%	Required + recommended Product fields
Title & meta	15%	Keyword placement, length, format
Image optimization	20%	Alt text, format, sizing, count
Content quality	20%	Unique description, specs, reviews
Internal linking	10%	Breadcrumbs, related products, categories
Technical	10%	Page speed, mobile rendering, canonical

---

2. Google Shopping Intelligence (DataForSEO Merchant API)

Live competitive analysis from Google Shopping results.

Cost Guardrail (MANDATORY)

Before EVERY Merchant API call:

"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run dataforseo_costs.py check merchant_google_products_search

• "status": "approved" -- proceed
• "status": "needs_approval" -- show cost, ask user
• "status": "blocked" -- stop, inform user

After each call:

"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run dataforseo_costs.py log merchant_google_products_search <cost>

Workflow

# Product search: who sells what at what price
"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run dataforseo_merchant.py search "<keyword>" --marketplace google

# Seller analysis: merchant ratings and dominance
"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run dataforseo_merchant.py sellers "<keyword>"

# Normalize results for analysis
"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run dataforseo_normalize.py results.json --module merchant

Analysis Outputs

Pricing Intelligence

• Price distribution: min, max, median, P25, P75
• Price outliers (> 2 standard deviations from median)
• Price-to-rating correlation
• Currency normalization to USD (or user-specified)

Seller Landscape

• Top 10 sellers by listing count
• Merchant rating distribution
• Free shipping prevalence
• New vs established sellers

Product Listing Quality

• Title keyword patterns in top listings
• Average rating and review count benchmarks
• Image count per listing
• Availability status distribution

Load references/marketplace-endpoints.md for full API parameter details.

---

3. Amazon Marketplace (DataForSEO)

Cross-marketplace intelligence comparing Google Shopping and Amazon.

Cost Guardrail (MANDATORY)

"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run dataforseo_costs.py check merchant_amazon_products_search

Amazon endpoints are in the warn_endpoints set -- always requires user approval.

Workflow

# Amazon product search
"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run dataforseo_merchant.py search "<keyword>" --marketplace amazon

# Cross-marketplace comparison
"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run dataforseo_merchant.py compare "<keyword>"

Cross-Marketplace Report

Metric	Google Shopping	Amazon
Avg price	$	$
Median rating	X.X	X.X
Avg review count	N	N
Top seller share	%	%
Free shipping %	%	%

---

4. Marketplace Keyword Gaps

Identify mismatches between organic and Shopping visibility.

Workflow

1. Fetch organic rankings via seo-dataforseo: dataforseo_labs_google_ranked_keywords for domain
2. Fetch Google Shopping presence via Merchant API: merchant_google_products_search for top organic keywords
3. Cross-reference results

Gap Types

Gap Type	Meaning	Action
Organic Only	Ranks organically but no Shopping ads	Create Google Merchant Center feed, bid on these keywords
Shopping Only	Shopping visibility but weak/no organic	Create content (buying guides, comparison pages) for these keywords
Both Present	Visible in both channels	Optimize: ensure price consistency, enhance schema
Neither	No visibility in either	Low priority unless high volume

Output Format

## Keyword Gap Analysis: example.com

### Opportunities: Organic → Shopping (12 keywords)
| Keyword | Organic Pos | Volume | CPC | Recommended Action |
|---------|------------|--------|-----|-------------------|

### Opportunities: Shopping → Organic (8 keywords)
| Keyword | Shopping Rank | Volume | CPC | Content Type Needed |
|---------|-------------|--------|-----|-------------------|

---

5. Product Schema Enhancement

Validate and generate Product schema following Google's current requirements.

Confirmed Required Properties (Google Merchant)

Confirmed required fields are name, image, and offers; use Offer, not AggregateOffer, for merchant listings.

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "",
  "image": [""],
  "offers": {
    "@type": "Offer",
    "url": "",
    "priceCurrency": "USD",
    "price": "0.00",
    "availability": "https://schema.org/InStock"
  }
}

Recommended Properties (Enhance Rich Results)

• sku -- product identifier
• description, brand, offers.seller -- recommended context fields
• gtin13 / gtin14 / mpn -- global trade identifiers
• aggregateRating -- star rating + review count
• review -- individual reviews (minimum 1)
• color, material, size -- variant attributes
• shippingDetails -- ShippingDetails with rate and delivery time (merchant-level shipping via ShippingService is also supported; shipping/returns can be set in Search Console without a Merchant Center account)
• hasMerchantReturnPolicy -- MerchantReturnPolicy with type and days
• hasAdultConsideration -- required for adult-oriented products (added 2026-05-20 to Product variant / Merchant listing); Google Search supports only the value https://schema.org/SexualContentConsideration
• category -- Text, CategoryCode, or an array mixing both. Use custom text for merchant-defined product types and CategoryCode with Google's taxonomy URL plus codeValue for Google Product Categories.

Validation Rules

1. price must be a number string, not "$29.99" (no currency symbol)
2. availability must use full Schema.org URL enum
3. image should be array with >= 1 high-res image URL
4. priceCurrency must be ISO 4217 (USD, EUR, GBP)
5. If brand is present, brand.name must not be empty or "N/A"
6. Sale periods use validFrom plus either validThrough or priceValidUntil, in ISO 8601 format. Include time and timezone when known.
7. If aggregateRating present: ratingValue and reviewCount required
8. Do not include fake reviews or undisclosed incentivized reviews in visible content or structured data. Clearly and prominently disclose incentives.

Schema Scoring

Completeness	Score
All required fields	50/100
+ aggregateRating	65/100
+ sku/gtin/mpn	75/100
+ shippingDetails	85/100
+ merchantReturnPolicy	90/100
+ reviews (3+)	100/100

---

Cross-Skill Integration

Skill	Integration Point
seo-schema	Delegates Product schema generation; reuses validation logic
seo-images	Product image audit (alt text, format, dimensions), plus DigitalSourceType: TrainedAlgorithmicMedia IPTC label for AI-generated product images (Merchant Center requirement)
seo-content	Product description E-E-A-T and uniqueness analysis
seo-dataforseo	Organic keyword rankings for gap analysis
seo-technical	Core Web Vitals for product pages (LCP on hero image)
seo-google	GSC indexation + Performance data for product URLs (NOT Merchant Center feed validation, that is done in Merchant Center / the Merchant API; the legacy Content API for Shopping sunsets 2026-08-18)

UCP: Universal Commerce Protocol (live)

Google-initiated open standard (co-developed with Shopify, Etsy, Wayfair, Target, Walmart; payment partners Visa/Mastercard/Stripe/Adyen/Amex) for letting AI agents discover, negotiate, and transact with merchants without one-off integrations. Google confirms a first reference implementation for conversational buying in AI Mode in Search. Broader Universal Cart rollout details are reported from Google I/O 2026 keynote coverage; not confirmed on a Google-owned source. ucp.dev lists 2026-04-08 as the latest release in its date-based versioning scheme, not 1.0; two integration paths: Native (default) and Embedded (approved merchants). Pairs with AP2 (reportedly moving toward FIDO governance). Canonical: developers.google.com/merchant/ucp and ucp.dev.

Merchants already on Google Merchant Center with clean Product schema can declare a UCP profile at /.well-known/ucp listing capabilities (dev.ucp.shopping.checkout, .fulfillment, .discount). See references/ucp-universal-commerce-protocol.md for audit criteria, capability examples, and the relationship to AP2 (Agent Payments Protocol).

Audit command

# Discover and validate the UCP profile
"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run ucp_check.py https://store.example.com --json

# With endpoint reachability probes (HEAD each declared capability)
"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run ucp_check.py https://store.example.com --probe-endpoints --json

The script returns: profile presence, version, declared capabilities, structural issues (missing fields, unknown capability IDs), and (with --probe-endpoints) per-endpoint reachability. SSRF-blocked endpoints are reported explicitly. Missing profile is reported as opportunity, not failure. UCP itself is live; what's early is broad merchant adoption. Flag a literal "version": "1.0" as invalid (UCP versions are date-based, e.g. 2026-04-08).

---

Error Handling

Error	Cause	Response
No Product schema found	Page lacks JSON-LD	Analyze page content, generate recommended schema
DataForSEO credentials missing	Env vars not set	Run analysis without marketplace data, note limitation
Cost check blocked	Daily budget exceeded	Inform user, offer free-only analysis
Empty Shopping results	No products for keyword	Suggest broader keyword, check location settings
Amazon API timeout	Network/rate limit	Retry with backoff, fall back to Google-only
Invalid URL	Malformed input	Validate via google_auth.validate_url(), show error
Non-product page	URL is category/homepage	Detect page type, suggest /seo ecommerce schema instead

---

Output Template

## E-commerce SEO Report: [URL or Keyword]

### Overall Score: XX/100

### Product Page SEO
- Schema Completeness: XX/100
- Title & Meta: XX/100
- Image Optimization: XX/100
- Content Quality: XX/100
- Internal Linking: XX/100

### Marketplace Intelligence (if DataForSEO available)
- Google Shopping Listings: N products found
- Price Range: $XX - $XX (median: $XX)
- Top Seller: [name] (XX% market share)
- Amazon Comparison: [available/not checked]

### Top Recommendations
1. [Critical] ...
2. [High] ...
3. [Medium] ...

Generate a PDF report? Use `/seo google report`

Other files in this skill

• references/marketplace-endpoints.md
• references/ucp-universal-commerce-protocol.md

references/marketplace-endpoints.md (verbatim)

DataForSEO Merchant API Reference

Endpoint details for Google Shopping and Amazon marketplace data.

Endpoints

Google Shopping Products

Field	Value
Endpoint	merchant_google_products_search
Method	POST (task) / GET (results)
Cost	$0.02 per call
Queue	Standard (60-80% savings vs live)

Parameters:

• keyword (required) -- search query
• location_code (default: 2840 = US) -- DataForSEO location ID
• language_code (default: "en") -- language
• price_min / price_max (optional) -- filter by price range
• sort_by (optional) -- "relevance", "price_low_to_high", "price_high_to_low", "rating"
• depth (optional, default: 100) -- number of results

Response fields:

• title -- product listing title
• price -- numeric price value
• currency -- currency code (USD, EUR, etc.)
• seller -- merchant name
• rating -- product rating (float, 0-5)
• reviews_count -- number of reviews
• url -- product listing URL
• image_url -- product image URL
• availability -- "in_stock", "out_of_stock", "preorder"
• delivery_info -- shipping details text
• product_id -- Google Shopping product ID

Google Shopping Sellers

Field	Value
Endpoint	merchant_google_sellers_search
Method	POST (task) / GET (results)
Cost	$0.02 per call

Parameters: Same as products search.

Response fields:

• seller_name -- merchant name
• seller_rating -- merchant rating (float)
• seller_reviews_count -- merchant review count
• price -- price offered by this seller
• delivery_info -- shipping and delivery text
• url -- seller listing URL

Amazon Products

Field	Value
Endpoint	merchant_amazon_products_search
Method	POST (task) / GET (results)
Cost	$0.02 per call
Note	In warn_endpoints -- always requires user approval

Parameters:

• keyword (required) -- search query
• location_code (default: 2840 = US)
• language_code (default: "en")
• depth (optional, default: 100)
• sort_by (optional) -- "relevance", "price_low_to_high", "price_high_to_low", "avg_customer_review"

Response fields:

• title -- product title
• price -- numeric price
• currency -- currency code
• seller -- seller/brand name
• rating -- star rating (float, 0-5)
• reviews_count -- review count
• url -- Amazon product URL
• image_url -- product image
• availability -- stock status
• asin -- Amazon Standard Identification Number
• is_prime -- Prime eligibility (boolean)
• is_best_seller -- Best Seller badge (boolean)

Task/Poll Pattern

All Merchant endpoints use the standard DataForSEO queue pattern:

1. POST task with parameters to create endpoint
2. Poll for results with exponential backoff (2s, 4s, 8s, max 60s)
3. GET completed results by task ID

This saves 60-80% compared to live endpoints.

Rate Limits

• Max 2000 tasks per minute (across all endpoints)
• Max 30,000 tasks per day on standard plans
• Backoff on HTTP 429: wait 60 seconds, then retry

Data Normalization

When consuming responses, normalize:

Field	Raw	Normalized
Price	String "$29.99" or float	Float 29.99
Currency	Mixed formats	ISO 4217 code (USD, EUR, GBP)
Availability	Various strings	Enum: in_stock, out_of_stock, preorder, unknown
Rating	Integer or float	Float rounded to 1 decimal
Reviews	String or int	Integer

Use "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run dataforseo_normalize.py --module merchant for automatic normalization.

Cost Reference

See skills/seo-dataforseo/references/cost-tiers.md for the full pricing table, budget presets, and cost reduction tips. All Merchant endpoints are $0.02/call on standard queue.

references/ucp-universal-commerce-protocol.md (verbatim)

UCP — Universal Commerce Protocol (June 2026)

UCP is a Google-initiated open standard, co-developed with Shopify, Etsy, Wayfair, Target, and Walmart (20+ endorsers), plus payment partners (Stripe, Visa, Mastercard, Adyen, Amex). Its purpose: let AI agents discover, negotiate, and transact with merchants without one-off integrations. It is interoperable with A2A (Agent2Agent), AP2 (Agent Payments Protocol), and MCP.

For commerce sites, UCP sits next to Google Merchant Center feeds and Google Business Profile as the third leg of agent-era discovery. Google confirms a first reference implementation for conversational buying in AI Mode in Search; broader Universal Cart rollout details are reported from Google I/O 2026 keynote coverage; not confirmed on a Google-owned source.

Primary sources (canonical, stable):

• Google merchant developer guide: https://developers.google.com/merchant/ucp (and /merchant/ucp/guides/ucp-profile)
• Spec / overview: https://ucp.dev. ucp.dev lists 2026-04-08 as the latest release in its date-based versioning scheme (YYYY-MM-DD); revalidate before using it as a hard validator.

What UCP is and isn't

What it is	What it isn't
A capability-declaration + negotiation protocol	A new payment processor
Transport-agnostic (REST, MCP, A2A)	A replacement for Merchant Center feeds
Compatible with AP2 (Agent Payments Protocol) for cryptographic user-consent proof on autonomous purchases	A way to skip being merchant of record
Google reference implementation for conversational buying in AI Mode in Search	A "ranking factor" because Google has not framed it that way

Merchants stay Merchant of Record under UCP — they keep customer relationships and post-purchase ownership.

How to declare a UCP profile

Publish a profile at /.well-known/ucp describing capabilities and versions. The general shape (consult the live spec for exact field names):

{
  "version": "2026-04-08",
  "capabilities": [
    {
      "id": "dev.ucp.shopping.checkout",
      "version": "2026-04-08",
      "endpoint": "https://api.example.com/ucp/checkout"
    },
    {
      "id": "dev.ucp.shopping.fulfillment",
      "version": "2026-04-08",
      "endpoint": "https://api.example.com/ucp/fulfillment"
    },
    {
      "id": "dev.ucp.shopping.discount",
      "version": "2026-04-08",
      "endpoint": "https://api.example.com/ucp/discount"
    }
  ],
  "merchant": {
    "name": "Example Co.",
    "id": "merchant-center-id-here"
  }
}

UCP uses date-based versioning (YYYY-MM-DD), current release 2026-04-08 — a literal "1.0" does not match any real UCP release and will fail the spec's version negotiation. Platforms (AI Mode in Search, Gemini, and eventually others) auto-discover the profile and negotiate.

Integration paths

• Native checkout (default) — full agentic potential; the recommended path.
• Embedded checkout (optional, iframe-based) — for specific Google-approved merchants with complex/bespoke checkout.

Merchants join a waitlist and must be Google-approved before going live.

Common capabilities to declare

Capability ID (shape)	Purpose
dev.ucp.shopping.checkout	Initiate checkout, return totals + payment intent
dev.ucp.shopping.fulfillment	Quote shipping options and delivery windows
dev.ucp.shopping.discount	Apply promo codes / loyalty discounts at quote time
dev.ucp.shopping.cart	Add / remove / update items in agent-managed carts

Exact identifiers are governed by the live spec. The namespace pattern is dev.ucp.<domain>.<verb>; version values are date-based.

What claude-seo audits

/seo ecommerce <url> should report:

1. Presence: does /.well-known/ucp resolve to a valid JSON document?
2. Capability coverage: which capabilities are declared? Flag missing checkout / fulfillment / discount as opportunities, not failures (the protocol is early).
3. Endpoint reachability: are declared endpoints HTTPS, valid TLS, not returning 5xx?
4. Version coherence: is the declared version a valid date-based (YYYY-MM-DD) UCP release? ucp.dev lists 2026-04-08 as latest; revalidate before flagging a version as invalid. Flag a literal "1.0" or unrecognized version as invalid.
5. Integration path: does the profile imply Native (default) or Embedded (approved-merchant) checkout?

The audit should not score the absence of UCP as a critical failure — frame it as an opportunity, especially for merchants already on Google Merchant Center. (UCP itself is live; what's "early" is broad merchant adoption.)

How UCP interacts with existing surfaces

Existing surface	Relationship to UCP
Google Merchant Center feed	Required upstream — UCP capabilities reference Merchant Center products by ID
Google Business Profile	Independent — UCP is product / order; GBP is store / location
Product schema (hasMerchantReturnPolicy, shippingDetails)	Complementary — UCP exposes the same data at the API layer; schema exposes it at the page layer
AP2 (Agent Payments Protocol)	Pair. UCP handles discovery + checkout structure; AP2 handles cryptographic proof of user consent. Treat FIDO governance, v0.2, and Mastercard Verifiable Intent details as secondary-source context, not canonical audit guidance until primary sources verify them.

A merchant that already has clean Merchant Center feeds, complete Product schema, and a checkout API can declare a UCP profile in a sprint.

Audit posture

• Tier 1 (e-commerce sites already on Merchant Center): recommend declaring a UCP profile as a forward-looking opportunity.
• Tier 2 (DTC sites not on Merchant Center): do not recommend UCP yet — Merchant Center is the prerequisite to most flows.
• Tier 3 (informational / B2B sites): ignore UCP — but do not blanket- exclude hospitality/restaurant sites: UCP is expanding to Lodging and Food verticals (hotel booking in AI Mode, food delivery via Google Maps).

Current rollout & landscape (2026)

• Universal Cart rollout details beyond AI Mode in Search are reported from Google I/O 2026 keynote coverage; not confirmed on a Google-owned source. Treat Gemini app, YouTube/Gmail, country expansion, and retailer lists as hedged context. Confirmed audit guidance remains Merchant Center eligibility, clean product data, and /.well-known/ucp readiness for AI Mode in Search.
• GML 2026 (2026-05-20): BNPL (Affirm, Klarna) in Google Pay; Direct Offers + Shopping ads on YouTube enabling instant purchase for UCP-integrated brands; AI performance insights + Ask Advisor in Merchant Center.
• Landscape: UCP is one of three agentic-checkout protocols — alongside OpenAI's Agentic Commerce Protocol (ACP) (its consumer Instant Checkout was pulled early March 2026) and Microsoft Copilot checkout via Shopify (2026-01-08). Keep ACP/Copilot as secondary-sourced context.

Last verified

2026-06-21. Re-check when:

• A new dated UCP spec supersedes 2026-04-08.
• AP2 advances past v0.2 / FIDO governance milestones change.
• UCP expands to new verticals or new surfaces (beyond Search, Gemini, YouTube, Gmail).

Back to seo skill (claude-seo: 25 sub-skills, 18 sub-agents) or Agent skills.