seo-ecommerce

SKILL.md

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:

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:

python3 scripts/dataforseo_costs.py log merchant_google_products_search <cost>

Workflow

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

python3 scripts/dataforseo_costs.py check merchant_amazon_products_search

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

Workflow

# 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

Fetch organic rankings via seo-dataforseo:
dataforseo_labs_google_ranked_keywords for domain

Fetch Google Shopping presence via Merchant API:
merchant_google_products_search for top organic keywords

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)

{
  "@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

price must be a number string, not "$29.99" (no currency symbol)

availability must use full Schema.org URL enum

image should be array with >= 1 high-res image URL

priceCurrency must be ISO 4217 (USD, EUR, GBP)

brand.name must not be empty or "N/A"

Dates in priceValidUntil must be ISO 8601

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

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