---
name: "SEO ecommerce"
repo: https://github.com/agricidaniel/claude-seo
source: https://github.com/agricidaniel/claude-seo/blob/HEAD/skills/seo-ecommerce/SKILL.md
license: "MIT"
install: "npx skills add agricidaniel/claude-seo --skill seo-ecommerce"
page: https://100xlab.com/resources/agent-skills/agricidaniel-claude-seo--seo-ecommerce--ibicem
---

# 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. python3 scripts/render_page.py <url> --mode auto → raw/rendered HTML
2. python3 scripts/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:
```bash
python3 scripts/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:
```bash
python3 scripts/dataforseo_costs.py log merchant_google_products_search <cost>
```

### Workflow

```bash
# Product search: who sells what at what price
python3 scripts/dataforseo_merchant.py search "<keyword>" --marketplace google

# Seller analysis: merchant ratings and dominance
python3 scripts/dataforseo_merchant.py sellers "<keyword>"

# Normalize results for analysis
python3 scripts/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)

```bash
python3 scripts/dataforseo_costs.py check merchant_amazon_products_search
```

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

### Workflow

```bash
# Amazon product search
python3 scripts/dataforseo_merchant.py search "<keyword>" --marketplace amazon

# Cross-marketplace comparison
python3 scripts/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.

### Required Properties (Google Merchant)

```json
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "",
  "image": [""],
  "description": "",
  "brand": { "@type": "Brand", "name": "" },
  "offers": {
    "@type": "Offer",
    "url": "",
    "priceCurrency": "USD",
    "price": "0.00",
    "availability": "https://schema.org/InStock",
    "seller": { "@type": "Organization", "name": "" }
  }
}
```

### Recommended Properties (Enhance Rich Results)

- `sku` -- product identifier
- `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
- `hasMerchantReturnPolicy` -- MerchantReturnPolicy with type and days

### 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. `brand.name` must not be empty or "N/A"
6. Dates in `priceValidUntil` must be ISO 8601
7. If `aggregateRating` present: `ratingValue` and `reviewCount` required

### 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** | Google Merchant Center feed validation via GSC |

## UCP — Universal Commerce Protocol (forward-looking)

Google-led standard (co-developed with Shopify, Etsy, Walmart, Wayfair, Visa,
Mastercard, etc.) for letting AI agents discover, negotiate, and transact with
merchants without one-off integrations. Already powers direct buying from AI
Mode and Gemini.

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

```bash
# Discover and validate the UCP profile
python3 scripts/ucp_check.py https://store.example.com --json

# With endpoint reachability probes (HEAD each declared capability)
python3 scripts/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 adoption is early.

---

## 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`
```

---

## Supporting file: references/marketplace-endpoints.md

# 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 `scripts/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.

---

## Supporting file: references/ucp-universal-commerce-protocol.md

# UCP — Universal Commerce Protocol (May 2026)

UCP is a Google-led open standard, co-developed with Shopify and endorsed by
Etsy, Target, Walmart, Wayfair, plus payment partners (Stripe, Visa,
Mastercard, Adyen, Amex). Its purpose: let **AI agents discover, negotiate,
and transact with merchants without one-off integrations**.

For commerce sites, UCP sits next to **Google Merchant Center feeds** and
**Google Business Profile** as the third leg of agent-era discovery. Adoption
is early but the cost of declaring a profile is low.

**Primary source:** Google AI optimization guide references UCP; the spec
itself is co-published at developer.google.com / merchant.google.com (consult
Google for the current canonical URL — the standard is moving).

## 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 |
| Adopted by AI Mode in Search and Gemini today | A "ranking factor" — 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):

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

Platforms (AI Mode in Search, Gemini, and eventually others) auto-discover
the profile and negotiate. Google has built a reference implementation
powering direct buying from AI Mode and Gemini.

## 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 pattern is
`dev.ucp.<domain>.<verb>` with semantic versioning.

## 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:** does the declared protocol version match a known
   release? Flag pre-release or unrecognized versions.

The audit should **not** score the absence of UCP as a critical failure today
— adoption is early. Frame it as a forward-looking opportunity, especially
for merchants already on Google Merchant Center.

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

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 entirely.

## Last verified

2026-05-18. The standard is moving fast. Re-check when:

- The canonical spec URL stabilizes (currently published on Google developer
  docs, but exact path may change).
- AP2 reaches stable release.
- Additional platforms (beyond AI Mode + Gemini) announce UCP consumption.