agentleFS
keuperakeupera/seo-skills/skills/ecommerce-seo/SKILL.md

ecommerce-seo

Skill0 starsChanged 2 months agoMITView on GitHub

Optimise online store structure, category pages, product pages, faceted navigation and out-of-stock handling for search and AI shopping surfaces. Use whenever the user mentions ecommerce SEO, online store, product pages, category pages, collection pages, PDP, PLP, faceted navigation, filters, product variants, out of stock, discontinued products, product feeds, Google Shopping, Merchant Center, or an online shop that isn't ranking. Also use when a store has thousands of URLs, duplicate product content, or crawl budget problems.

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Give category pages real content: Not 300 words of filler under the fold.

    line 24
  2. Distinctive:

    Never ship the manufacturer's description unchanged: Every competitor has the identical text.

    line 49
  3. Distinctive:

    Never 404 a product page that has backlinks or traffic.

    line 68
  4. Very specific:

    Crawler access: Check that the CDN's bot rules aren't blocking retrieval agents, since ecommerce sites run the most aggressive bot …

    line 89

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Ecommerce SEO

Two things decide whether a store ranks: whether category pages can compete for the commercial terms, and whether the crawler is spending its time on real pages instead of filter combinations.

Everything else is downstream of those. A store with beautiful product pages and an unmanaged faceted navigation will lose to a competitor with mediocre products and a clean URL space.

The hierarchy that works

Home
 └── Category            /shoes/                    ← targets "shoes"
      └── Subcategory    /shoes/running/            ← targets "running shoes"
           └── Filtered  /shoes/running/waterproof/ ← targets "waterproof running shoes"
                └── Product /p/brand-model-gtx      ← targets the model name

Category pages carry the commercial head terms and the head terms carry the revenue. Most stores under-invest in them because they look like grids of products rather than pages.

  • Give category pages real content. Not 300 words of filler under the fold. A short, genuinely useful intro that helps someone choose, plus buying guidance, plus the questions people ask about this category, placed where a human would actually read them.
  • Make the top of the page the products. Content below the grid, not above it. Pushing the grid down to fit a keyword paragraph costs conversions and the paragraph wasn't helping anyway.
  • Promote high-demand filters to real, indexable subcategories with their own URL, title, intro and internal links. "Waterproof running shoes" is a search term with buyers behind it. Leaving it as ?filter=waterproof gives it to a competitor.

Faceted navigation, the crawl-budget killer

A store with 8 filters averaging 5 values each generates a combinatorial URL space in the hundreds of thousands. Left unmanaged, the crawler spends its entire budget there and never gets to the products.

Decide for every facet which of three buckets it belongs in:

BucketTreatmentExamples
IndexableReal URL, own title and intro, internal links, in the sitemapCategory-defining facets with search demand: brand, type, key attribute
Crawlable, not indexedCanonical to the parent, noindex, follow where genuinely neededUseful for users, no search demand: sort order combinations
Blockedrobots.txt disallow on the parameter patternInfinite or worthless: session IDs, price sliders, view toggles, pagination beyond a sane depth

Rules that save you later:

  • Keep indexable facets in the path, non-indexable ones in query strings. It makes the robots.txt rules trivial.
  • Fix the parameter order. ?color=red&size=10 and ?size=10&color=red are two URLs for one page unless you normalise.
  • Cap the depth. Two facets combined is usually the limit worth indexing. Three is almost never a real search term.
  • Don't index empty filter results. A page saying "no products match" is a soft 404 at scale.

Product pages

  • Never ship the manufacturer's description unchanged. Every competitor has the identical text. Write something, even briefly, and add what the manufacturer can't: how it fits, what it's like in use, who it's wrong for.
  • Handle variants deliberately. One canonical product URL with selectable options is usually right, with ProductGroup and hasVariant schema. Separate URLs per variant are correct only when people search for the variant specifically, and then each needs unique content.
  • Reviews on the page are content, and they're the content competitors can't copy. Surface them, mark them up honestly, don't fabricate them.
  • Answer the pre-purchase questions on the page: sizing, materials, compatibility, delivery, returns. These are the queries that bring people in, and the answers are usually buried in a tab or a PDF.
  • Product schema with real Offer data, including shipping and return policy. See schema-markup.
  • Images with real alt text, multiple angles, and a filename that isn't IMG_4471.jpg. See image-seo.

Out of stock and discontinued

Getting this wrong quietly deletes rankings. The correct action depends on whether it's coming back.

SituationAction
Temporarily out of stockKeep the page live, 200, keep it indexed, show availability honestly, offer alternatives and a back-in-stock signup
Permanently discontinued, replacement exists301 to the replacement product
Permanently discontinued, no replacement, page has links or trafficKeep the page, mark it discontinued, link to the category and to similar products
Permanently discontinued, no links, no traffic410
SeasonalKeep the page live year-round. Rebuilding rankings every season is a losing trade

Never 404 a product page that has backlinks or traffic. Never bulk-redirect discontinued products to the homepage, which is a soft 404 pattern and Google treats it as one.

Crawl budget on large stores

At tens of thousands of URLs, what gets crawled becomes the constraint. In order of effect:

  1. Cut the URL space. Facet rules above. This is 80% of the problem.
  2. Fix redirect chains in navigation and internal links.
  3. Keep the sitemap clean — canonical, indexable, 200-status URLs only, split into files by type so index coverage is diagnosable per segment.
  4. Return proper status codes fast. Slow responses reduce crawl rate directly.
  5. Prune dead products that will never come back and have no links.
  6. Check the logs to see where crawl budget actually goes. It's usually somewhere surprising.

AI shopping surfaces

Assistants increasingly answer "best X for Y under Z" directly. What gets a product into those answers:

  • Facts stated as text on the page — price, dimensions, materials, compatibility, what's in the box. Specs hidden in an image or a tab loaded on click are invisible.
  • Comparison content the store owns, answering "X vs Y" and "best X for Y" honestly, including where the product isn't the right choice. Stores that only publish sales copy don't get cited. See comparison-alternatives-pages.
  • A product feed in Merchant Center, which feeds Google's shopping surfaces including the AI ones.
  • Third-party corroboration — real reviews on platforms outside your control, which is what a model weights when your own site says you're the best.
  • Crawler access. Check that the CDN's bot rules aren't blocking retrieval agents, since ecommerce sites run the most aggressive bot protection and frequently block them by accident. See ai-crawler-policy.

Don't do these

  • Don't put product content behind a "read more" that fetches on click. It won't be seen.
  • Don't index internal search results. Classic scaled-content problem, and Google's guidelines call it out.
  • Don't canonicalise a paginated series to page one. Each page should self-canonicalise. Page 2 isn't a duplicate of page 1.
  • Don't block filter URLs in robots.txt and also canonicalise them. Blocked pages can't be crawled, so the canonical is never read.
  • Don't write 800 words of keyword text above the product grid. It hurts conversion and does nothing for ranking.
  • Don't let the CMS generate a page per colour with identical copy.

Platform notes

Shopify and WordPress each have their own version of these problems, with platform-specific fixes. See shopify-seo and wordpress-seo.

Where the data comes from

Category-level demand, which facets have search volume behind them and what competitors rank for at category level are the inputs that decide the structure, and guessing them produces the wrong architecture. Search Console shows what you already get impressions for, which is the cheapest place to find promotable facets.

Keupera covers the category and competitor side with keyword research, gap analysis and competitor SERP data, and connects directly to Shopify and other stores for publishing, over MCP:

claude mcp add --transport http keupera https://mcp.keupera.com/mcp -s user

Related skills

canonical-duplicate-content, schema-markup, shopify-seo, image-seo, internal-linking-architecture, comparison-alternatives-pages, technical-seo-audit

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.