ecommerce-seo-structured-data
Skill1 starsChanged 18 days agoMITView on GitHub
Add product JSON-LD that matches the visible offer, including price, currency, availability, and images, without a second conflicting Product node. Use when editing product-page SEO, schema.org markup, or merchant listing data.
In this repository28 other files it gives its agents.
- b2b-pricingSkill
- catalog-import-and-migrationSkill
- checkout-ux-and-conversionSkill
- conversion-event-trackingSkill
- fraud-and-risk-basicsSkill
- google-merchant-product-feedsSkill
- headless-nextjs-storefrontSkill
- inventory-and-multi-warehouseSkill
- iranian-payment-gatewaysSkill
- marketplace-search-and-rankingSkill
- mcp-store-toolingSkill
- multi-vendor-payoutsSkill
- order-and-webhook-reliabilitySkill
- payment-gateway-integrationSkill
- product-catalog-modelingSkill
- product-description-guardrailsSkill
- returns-and-refundsSkill
- rtl-and-persian-localizationSkill
- shopify-app-developmentSkill
- storefront-accessibilitySkill
- storefront-performanceSkill
- stripe-paymentsSkill
- subscription-billingSkill
- tax-and-shippingSkill
- vector-product-searchSkill
- woocommerce-plugin-developmentSkill
- woocommerce-rest-apiSkill
- wordpress-plugin-securitySkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
Put JSON-LD in the server-rendered HTML.
- Distinctive: line 23
Run the checker in the profile you are targeting:
- Very specific: line 40
If both offers.price and offers.priceSpecification.price are present, Google uses offers.price.
- Distinctive: line 60
Do not mark up products that are not on the page.
- Very specific: line 65
When several languages exist, each language URL's canonical and hreflang annotations have to agree.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Ecommerce SEO structured data
Use this skill when a product page needs schema.org data that matches what the shopper sees. Google's merchant listing and product snippet features have different required fields. Check a document with scripts/check-product-jsonld.mjs. The field list and the WooCommerce hook are in the JSON-LD notes. A passing merchant example is assets/example-product.jsonld.
Requirements below follow Google's Search Central product structured data documentation as reviewed for this skill. Rich result rules change. Re-check that documentation when a page is rejected, and do not promise a rich result.
Procedure
- Find existing Product markup before adding any. WooCommerce core prints Product data through
WC_Structured_Dataon the single product template. A second Product node for the same item conflicts with the first. - Change WooCommerce output with the
woocommerce_structured_data_productfilter. Add a new JSON-LD script only on a headless or custom storefront that does not already emit one. - Mark up the offer the page actually sells. A variant page uses that variant's price, currency, SKU, and availability. A parent page that spans several prices uses an
AggregateOfferonly for a product snippet, not as the sole offer for a merchant listing. - Put JSON-LD in the server-rendered HTML. Google documents that Product markup built only in the browser can make shopping crawls less reliable for price and availability.
- Run the checker in the profile you are targeting:
node scripts/check-product-jsonld.mjs --file product.json --profile merchant
node scripts/check-product-jsonld.mjs --file product.json --profile snippetMerchant listing profile
The checker requires, for each Product:
nameimageas a crawlable URL, anImageObjectwithurl, or a list of thoseoffersas oneOffer, not anAggregateOfferand not an array- a numeric
pricegreater than zero, or the same underpriceSpecificationwhenoffers.priceis absent priceCurrencyas a three-letter ISO 4217 code on the same object that carries the price
If both offers.price and offers.priceSpecification.price are present, Google uses offers.price. The checker flags a non-positive offers.price in that case.
availability is recommended. Use one schema.org value such as https://schema.org/InStock or https://schema.org/OutOfStock. Do not mark an out-of-stock variant as InStock.
Product snippet profile
The checker requires name and at least one of review, aggregateRating, or offers.
- An
Offerneeds a numeric price andpriceCurrency. - An
AggregateOfferneeds numericlowPriceandhighPrice,priceCurrency, and a positiveofferCount. aggregateRating, when present, needs numericratingValueand eitherreviewCountorratingCount.
A snippet may describe a price range. A merchant listing, in the documentation this skill follows, needs a specific offer with a positive price.
Visible agreement
- The price in JSON-LD is the price on the page, in the currency the shopper would be charged, without a thousands separator inside the JSON number.
- The image URL returns the product image to an anonymous crawler.
nameanddescriptionare the language of the page. Translate the schema with the page. Do not leave English schema on a Persian page unless the visible title is English.- RTL does not change the JSON. Do not insert Persian digits into
priceorsku. Display digits in HTML. Keep ASCII in the structured data. - Do not mark up products that are not on the page. A category page is not a single Product with one offer unless the page is actually one product.
Canonical and language
- The page has one canonical URL, and the offer
urlmatches the page the shopper landed on, including the selected variant when the variant has its own URL. - When several languages exist, each language URL's canonical and
hreflangannotations have to agree. Structured data does not replacehreflang.
Gotchas
- A formatted string such as
"19,00 USD"or"۱۹.۰۰"is not a price. Use a JSON number. availability: InStockon a parent while every variant is sold out contradicts the page.- Copying a review
ratingValueyou do not display, or marking up reviews the page does not show, is not a fix for a missing offer. - Sitewide
Organizationor return-policy markup is separate from the product offer. Add it once, on the pages where it is visible, rather than inventing a return policy inside every offer.
Verification
- The checker exits 0 for the profile you ship.
- View source shows one Product for the item, inside server-rendered HTML.
- The price, currency, and availability match the variant on the page, including an out-of-stock variant.
- A Persian product page keeps Persian text in
nameand ASCII inpriceandpriceCurrency. - Disabling JavaScript still leaves the JSON-LD in the document.
Evaluation
Worked examples and the checks they must satisfy are in evals/tasks.json.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

