ecommerce-store-optimization

name

ecommerce-store-optimization

description

Build or audit e-commerce stores (Shopify and similar) optimized for conversion, trust, and SEO — covering color/emotion, storytelling, social proof, trust badges, checkout UX, visual content, EU legal compliance, SEO, and price psychology. Use WHENEVER the user wants to create a new e-commerce store or product page, redesign/improve an existing one, or asks to "audit", "check", "score", "optimize", or "review" a store/boutique for conversion, UX, trust, or SEO — even phrased casually ("regarde ma boutique", "améliore ma fiche produit", "pourquoi ça convertit pas", "check mon Shopify"). Two modes: BUILD (design a store/page from a brief) and AUDIT (score a live store or URL against a weighted checklist, return prioritized fixes). Pairs with landing-page-design for front-end execution and the Shopify connector for live-store audits/edits. Not for pure backend/inventory logic or ad-creative-only requests (use ad-image-prompt-structure instead).

E-commerce Store Optimization

A method for building or auditing e-commerce stores against the 9 pillars of a store that converts: it looks intentional, it earns trust fast, and it gets out of the buyer's way. This skill is a checklist + a workflow, not a single template — apply the pillars to whatever product/brand the user has.

Two modes — figure out which one first

• BUILD — the user wants to create or redesign a store, a product page, or a specific section. Use the 9 pillars below as the design brief, then hand off actual front-end construction to the landing-page-design skill (or Shopify theme edits via the Shopify connector if the store already exists on Shopify). This skill supplies what to build and why; landing-page-design supplies how to build it visually.
• AUDIT — the user wants an existing store (theirs, or a competitor's URL) scored and prioritized. Use references/audit-scoring-grid.md for the scoring template. If it's the user's own connected Shopify store, pull real data first (see "Auditing a live Shopify store" below) rather than guessing.

If ambiguous, ask which one in one line — don't assume.

The 9 pillars

Pillar 0 — Audience & niche fit (the lens over all 9 pillars)

Before applying any pillar, translate it through who is buying and in what niche. The audience is not one more checkbox — it's the lens that sets the intensity and register of every other pillar. The same "add reassurance" or "pick a palette" instruction produces a very different store depending on the niche.

The register is a variable, not a preset. The rows below are illustrations of how the lens shifts across niches — they are NOT templates to match, and none is a default. Derive the register from the user's actual stated niche/audience; if the niche isn't one of these, reason it from first principles. Keep each row's styling inside its own niche — never import one niche's register into another:

• Feminine fashion / beauty → tends warmer/richer/multi-color; higher visual density; enticing hero; UGC / before-after / community proof; emotional, identity-driven copy — seduce and de-risk.
• Clinical / wellness / supplements → tends restrained; proof-led; study / ingredient / expert proof; sober, evidence-driven copy.
• Tech / B2B / tools → tends crisp/neutral; spec-and-outcome proof (logos, numbers); trust-forward, low-ornament copy.
• Other niches (kids/family, luxury, outdoor, food, masculine grooming…) each shift the register again — infer, don't borrow from the rows above.

Guardrail against over-anchoring: if the user's niche is unstated or ambiguous, ask (or state your inference explicitly) — do not silently fall back to the fashion row or any other listed example just because it's the most vivid. A store must read right for its own niche; a men's-tool store styled like a beauty drop is as much a fit failure as the reverse.

So for every pillar below, first ask "what does this audience in this niche expect here?" and calibrate to that — a store that looks wrong for its niche fails on fit even if each individual pillar is technically "present." In BUILD, capture the niche archetype + desired register up front (workflow step 1). In AUDIT, the scripts surface an audience-fit calibration flag (coherence of palette, visual intensity, social-proof type and copy register vs. the stated niche) — reported separately from the weighted score, as a mismatch warning.

1. Color & emotion

The palette must evoke the product's promise, not just "look nice." Pick 1 dominant color that carries the core emotion (calm, energy, trust, luxury...), 1 secondary, 1 accent for CTAs — 60:30:10 split. Ground it in the real product's own colors/context AND in the audience lens (Pillar 0), calibrated to the store's actual niche — not to whichever example was most vivid. Never a generic default (e.g. don't default to pink for "wellness" unless the product or audience genuinely calls for it). Check contrast: the CTA color must never be a color also used for warnings/errors elsewhere.

2. Soul & storytelling

A store with no story is a commodity store. Every store needs:

• A founder/brand story — a short "why this exists" narrative, ideally with a real photo/video, not stock imagery. This is what separates a brand from a dropship page in the visitor's mind.
• Real customer reviews — with names, (photos when possible), specific outcomes — not generic "great product!" text.
• Credible third-party quotes/mentions — press, known figures, or recognizable social proof, only if genuinely obtainable; on a live store never fabricate quotes or attribute them to real people without basis (labeled placeholders during dev are fine — see Placeholders vs live content).
• A consistent narrative thread from the ad → landing → product page → email (same promise, same voice).

Placeholders (dev/build) vs live content — rule

While building/dev, you MAY scaffold with clearly-labeled placeholder content (sample reviews, an average rating, an orders/stock counter, a demo crossed-out price) so the page can be assembled and previewed — this is legitimate and often necessary to build the layout. Two strict conditions:

1. Labeled as placeholder — code comment, an [EXAMPLE]/[DEMO] prefix, or obvious dummy data — so it can never be mistaken for real.
2. Replaced with genuine data before go-live. The moment the store serves real customers (live), every review / counter / crossed-out price must be authentic: showing fabricated ones to a real shopper is deceptive and illegal (EU Omnibus Directive, US FTC). When AUDITing a live store, a placeholder left online = red flag.

3. Immediate trust (above the fold)

The visitor must feel safe within the first 3 seconds:

• Trust badges visible in the hero (secure payment, satisfaction guarantee, verified reviews) — not buried in the footer.
• A one-sentence benefit-led promise (not a feature list) directly under/over the product visual.
• Honest real-time social proof if available (recent orders, review count). Never show fake counters to real customers on a live store; clearly-labeled placeholders during dev/build are fine and must be swapped for genuine data before go-live (see Placeholders vs live content).
• Message match: the hero's visual/promise must be the same one used in the ad that brought the visitor in. A mismatch is an instant bounce — critical when auditing paid-traffic landing pages (e.g. Meta ads → PDP).

4. Checkout & UX (1–2 clicks to order)

• Guest checkout by default — never force account creation.
• Minimal form fields — every extra field raises abandonment.
• Multiple payment methods: card, PayPal/Apple Pay, and split payment (Alma/Klarna-style) — installments lower the psychological price barrier even when the total is identical.
• A visible progress indicator in multi-step checkouts.
• Sticky/persistent "Add to cart" or "Buy now" CTA on mobile scroll.

5. Visual-first content

Assume the visitor will not read paragraphs. Prioritize:

• A hero visual (photo or short video) over hero text.
• Benefit-led bullet points (outcome, not spec: "s'endort en 8 min", not "chauffe à 42°C").
• Product-in-use video/GIF, not just static studio shots.
• Icons/visual anchors for guarantees, shipping, and specs instead of dense paragraphs.
• Ban empty quality-superlatives as standalone claims — "premium", "haut de gamme", "ultra qualité", "high-end" carry zero information on their own; buyers now read them as generic filler, not proof. This is the "sell the sizzle, not the steak" principle: a label never sells as well as a full sentence that puts the buyer inside the felt sensory/emotional experience the product actually delivers. Replace the adjective with a scene: not "matériau premium" but "le tissu qui garde ta main au chaud même à -5°C"; not "voiture premium" but "cette voiture te fait ressentir le silence." Applies to headlines, hero copy, and bullets alike — anywhere a quality-adjective is doing the selling instead of an image-in-words.

Standards de chrome (toute boutique — obligatoire, dès le build)

Trois éléments que chaque boutique doit avoir ; les poser par défaut, sans attendre qu'on les demande :

1. Logo en SVG — un vrai logo de marque au format SVG (net à toutes les tailles, léger, sert de base au favicon). Fallback PNG si un emplacement n'accepte pas le SVG. Placé dans le header (repris en footer). Jamais un simple texte brut à la place. Si aucun logo n'existe encore, en générer/proposer un — ne pas laisser la marque nue.
2. Image header / hero — une bannière visuelle en haut de la home (et idéalement en tête de PDP) : photo lifestyle ou produit-en-contexte, avec la promesse benefit-led en surimpression + le CTA. C'est le standard universel ; une home sans hero visuel fait « page dropship ». Respecter le message match (même visuel/promesse que la pub qui amène le visiteur).
3. Bandeau d'avis entreprise slidant — un ruban horizontal auto-défilant (marquee) d'avis clients / note globale près du hero et/ou au-dessus du CTA : ★★★★★ + note /5 + citations courtes qui défilent. En dev/build : placeholders clairement étiquetés OK ; en live : avis authentiques uniquement (voir Placeholders vs live content). Accessibilité : respecter prefers-reduced-motion (défilement en pause), pause au survol, texte lisible et non tronqué.

6. Reassurance on every page — not just the homepage

Trust signals must repeat contextually on every page type:

• PDP: badges, reviews, guarantee, FAQ objections just above the final CTA.
• Cart: reassurance on shipping time + return policy, not just a price summary.
• Checkout: security badges again, clear delivery estimate.
• Policy pages: written in plain, reassuring language — not just legal boilerplate dumped with no framing.

7. EU legal & compliance

Non-negotiable for a store selling into the EU:

• Cookie/RGPD banner that's actually configurable (accept/reject/customize), not just a dismiss-only notice.
• Prices displayed TTC (all taxes included) with VAT mentioned — required in the EU; a price that flips at checkout destroys trust instantly.
• Mentions légales / SIRET reachable in 1 click from the footer, not buried.
• CGV, politique de retour, politique de livraison present and specific (real timeframes, real return window) — vague policies read as untrustworthy.
• If shipping from outside the EU or handling customs duties on low-value parcels, state this clearly at checkout, not as a surprise fee later.

8. SEO that actually works

• Every sentence must mean something — no keyword-stuffed filler; Google and readers both penalize it.
• Structured data (schema markup) on products so review stars can appear directly in search results.
• Descriptive alt text on every product image (accessibility + image SEO).
• Internal linking between product pages, policy pages, and any content/FAQ pages.
• Performance is SEO: mobile-first layout (most e-commerce traffic is mobile), compressed/WebP images, lazy loading — Core Web Vitals affect both ranking and whether a visitor waits past 3 seconds.

9. Price psychology

Treat the displayed number as a design element, not just a value:

• Avoid price endings that feel arbitrary or anxiety-inducing to the target buyer (e.g. a lone "7" can read as unstable/unfinished to some audiences) — test/ask which digit conventions feel "safe" vs "cheap" vs "unstable" for the specific market rather than assuming one universal rule.
• Anchoring: a crossed-out reference price must be credible and computed from real data — e.g. a pack's compare-at = quantity × unit price, never an invented ×2 (that destroys trust the moment a visitor notices). The −% badge is derived from the real anchor, not hardcoded.
• Lead with "à partir de X €" on the landing when several packs exist — the entry price lowers the perceived barrier, the pack sells on the PDP.
• Honest, specific promotions: a dated seasonal discount ("offre d'été jusqu'au 31/08") + optional countdown converts better and is more credible than a vague/permanent "offre de lancement".
• Reframe the price contextually ("less than a coffee a day"-type comparisons) when it helps, but only if it's honest.
• Keep numeric coherence across the whole page: price, review count, delivery days, discount % should all feel deliberate, not randomly generated.

Architecture d'achat : single-page vs two-step (landing → PDP)

Décider tôt comment le visiteur achète — c'est structurant :

• Single-page : galerie + sélecteur de pack + add-to-cart sur la landing. OK pour une offre ultra-simple.
• Two-step (recommandé dès qu'on veut une vraie page produit) : la landing présente (hook + présentation + preuve sociale + éducation) avec un bouton « Commander » qui navigue vers la PDP /products/<handle> ; la PDP vend (sélecteur Pack/Couleur/Taille
  • add-to-cart). Passer en two-step dès que tu veux une page produit propre + description technique + avis.
• Pourquoi le two-step gagne : landing plus légère et lisible · vraie page produit (bon SEO + trafic direct) · tracking plus propre (PageView sur la landing, ViewContent seulement sur la PDP) · place pour la description technique et les avis sans surcharger.

Squelette validé (template)

Landing :

1. Hero — image plein cadre + promesse 1 phrase + CTA → PDP.
2. Présentation produit — visuel | promesse + 4 bénéfices en bullets + prix « à partir de X € » + bouton Commander → PDP + réassurance.
   • 2b. Fiche technique — en accordéon <details> (ne pas inonder la page).
3. Avis slidants — carrousel juste sous la présentation (pas enterré en bas).
4. Éducation — Problème → Mécanisme → Comparatif (fonds alternés).
5. FAQ — accordéon.
6. CTA final → PDP.

PDP : bandeau titre → (galerie image + guide des tailles | carte achat : note, prix + badge promo, sélecteur Pack/Couleur/Taille, réassurance, description) → TrustBar → Avis → FAQ → CTA.

Règles de build réutilisables (terrain)

1. Le backend Shopify pilote le front — ne code pas ce que Shopify fait déjà : images par coloris = images de variantes (le front lit variant.image, zéro mapping en dur) ; ordre d'affichage + variante par défaut = ordre des valeurs d'option Shopify (1ʳᵉ valeur = défaut). Règle : avant de coder une logique produit, vérifier si la data Shopify la porte — régler côté data, le front suit.
2. Alléger — détails secondaires en accordéon ou renvoyés sur la PDP ; retirer le redondant ; rythme serré pour tomber vite sur les avis. Utiliser un kill-switch (const SHOW_X = false) pour tester un retrait sans supprimer le code.
3. Binder l'info concrète sur les contrôles — ex. pointures EU sur les boutons taille (S = 36-39…), guide des tailles dans le slider, étoiles pleines. Règle : un sélecteur qui répond à l'objection (« quelle taille ? ») convertit mieux.
4. Panier orienté AOV — barre de complétion (« +2 = 1 offerte »), auto-switch en pack (même couleur/taille) + bouton 1-clic, réassurance dans le panier, et robustesse race-condition côté serveur (relire le panier avant de le recomposer). Règle : le panier doit pousser le pack, pas juste afficher un total.
5. Preuve sociale haute + slidante > grille statique enterrée (cf. Standards de chrome).
6. Headless = tracking + CSP à câbler à la main — voir §Backend / Hydrogen et references/hydrogen-pixels.md (sinon attribution Meta cassée en silence).
7. Piège CSS des ancres — overflow-x: hidden sur un wrapper casse le scroll vers une #ancre ; utiliser overflow-x: clip + scroll-margin-top (header sticky).

Toujours : choisir 1 boutique de référence et disséquer sa STRUCTURE (pas le contenu) avant de dessiner (cf. Build workflow).

Backend & connectors readiness (Shopify)

A store isn't build-complete just because the front end looks right — the Shopify backend has to actually be ready to take a real order. Whenever building or launching a Shopify store, check/set up:

• Payment: Shopify Payments (or an alternative gateway) activated, and express checkout methods enabled (Apple Pay / Google Pay / PayPal) — ties into Pillar 4's multi-payment-method point.
• Legal pages actually configured in Shopify (Settings → Policies), not just written somewhere: politique de confidentialité, CGV, politique de retour, mentions légales — populated with real, specific text (ties into Pillar 7), not left as the default placeholder.
• Store connection: custom domain connected with SSL active, and the storefront actually published (not left password-protected) before it's considered launch-ready.
• Shipping & taxes: shipping zones/rates set for the target market, VAT handled correctly for EU sales.
• Checkout settings: guest checkout allowed, customer-account requirement off by default (ties into Pillar 4).
• Headless / Hydrogen stores — pixel wiring: first detect whether the storefront is Shopify Hydrogen (headless React/Remix on Oxygen) vs a Liquid theme. A Liquid theme auto-injects Shopify's pixels; Hydrogen does NOT — you must wire Analytics.Provider + per-route events and connect Meta Pixel/CAPI, GA4, etc., gated on consent (RGPD). Run scripts/pixel_check.py --url <store_url> (or --code <repo_path> for the source) to verify. If tracking is missing, say so explicitly and then wire it following references/hydrogen-pixels.md — a headless store with unwired pixels silently breaks Meta-Ads attribution, which is exactly the failure this skill exists to prevent.

Use the Shopify connector to verify what it can (get-shop-info for domain/plan/currency; graphql_query/graphql_schema — reachable via tool_search — for deeper settings like payment providers or policy text if needed). Some settings aren't exposed by the simpler tools — flag those explicitly and tell the user to confirm them directly in Shopify admin rather than assuming they're set correctly.

Auditing a live Shopify store

When the user asks to audit their own connected Shopify store rather than a generic URL:

1. Pull real data instead of guessing — use the Shopify connector's get-shop-info, search_products / get-product, and run-analytics-query (conversion rate, sessions, cart-to-checkout drop-off) tools to ground the audit in actual numbers.
2. Score against references/audit-scoring-grid.md using what you actually observed (product pages, policy pages, checkout flow description) — flag anything you can't verify directly (e.g. real page-load speed) rather than assuming it's fine.
3. Cross-reference known context already in memory (e.g. a previously-audited store's palette, price point, target audience) instead of re-asking for it.

Build workflow

1. Gather product intake if missing: product, category, real features/benefits, price, target audience + niche archetype (e.g. women's fashion, clinical wellness, B2B tool — this drives Pillar 0's register), desired emotional register / visual intensity (sober & proof-led ↔ warm, vivid & enticing), brand palette, market (language/country) — same intake bar as ad-image-prompt-structure; don't design blind.
2. Collect 1–3 reference stores — mandatory, every time, before designing anything. Ask the user for at least 1 and at most 3 "boutiques gagnantes" (competitor or not, same category or adjacent) whose direction artistique/structure is worth drawing from. If the user has none in mind, ask them to name any store they admire rather than picking references yourself — the point is their taste signal, not a generic pick.
3. Analyze the references structurally — never to copy, only to learn the pattern. web_fetch each reference URL and extract structure, not content to lift verbatim:
   • Landing page layout: where is the promo/offer placed relative to the hero, and relative to the product itself?
   • How the product is put forward (hero photo treatment, video, in-use demo, close-up vs. lifestyle shot).
   • Click depth to purchase: count the actual clicks/steps from landing to payment confirmation.
   • How the core product message/value prop is delivered (headline pattern, bullet structure, where proof/reviews sit relative to the CTA).
   • Section order top to bottom (hero → ? → ? → final CTA).
   • Where trust signals appear relative to the buy button. With 2–3 references, flag what repeats across all of them — that's a validated structural convention worth reusing — versus what's unique to one, which is a stylistic choice, not a rule to copy.
4. Walk the 9 pillars as a design brief, now informed by the reference analysis — decide concretely what each pillar means for this product (which trust badges, which story angle, which price ending), using the validated structural patterns from step 3 rather than starting from zero. Poser aussi les 3 standards de chrome (logo SVG dans le header, image header/hero avec promesse + CTA, bandeau d'avis entreprise slidant) — ils sont obligatoires sur toute boutique, voir Standards de chrome.
5. Hand off construction:
   • New front-end page/section → use landing-page-design for the actual build (it owns visual execution, motion, responsive layout).
   • Editing an existing Shopify store → use the Shopify connector tools (, , , etc.) directly.

Audit workflow

1. Confirm the target: user's connected store, or an external URL to review.
2. Gather evidence (Shopify data if connected, or web_fetch the URL/pages). For a URL audit you can run the automation layer instead of doing this by hand — see "Scripts" below (run_audit.py does steps 2–4 mechanically for the objective pillars and prepares the subjective ones for you).
3. Score each pillar using references/audit-scoring-grid.md.
4. Present: overall score, top 3–5 highest-impact fixes first (impact × effort, not just a flat list), then the full pillar-by-pillar breakdown.
5. Never invent data you didn't observe (e.g. don't claim a page-speed score without measuring) — mark it "à vérifier" instead.
6. If it's a code audit (a Hydrogen / headless repo, not just a rendered URL), run scripts/pixel_check.py --code <path> to verify analytics/pixel wiring in the source (Hydrogen Analytics.Provider, Meta Pixel/CAPI, GA4, consent gating). Report missing wiring as a Tracking & pixels flag (separate from the weighted score); for a live-URL audit use --url instead, and mark consent-gated pixels "à confirmer" rather than asserting they're absent.

Scripts (automation layer)

The scripts/ folder turns this skill from a checklist into something that executes. Use it whenever code execution is available; fall back to reasoning through the workflow by hand if it isn't. All scripts are model-agnostic — they run on Opus or Fable; set STORE_SKILL_MODEL (or --model) to pick.

How "deploy a Claude agent" works here (important): the subjective pillars (color/emotion, storytelling, copy quality, per-page reassurance) need judgment, so they're dispatched through agents.py, which behaves two ways:

• API backend present (ANTHROPIC_API_KEY set, e.g. Claude Code) → it makes real Claude sub-agent calls, one per pillar.
• No key (typical inside a Claude.ai session) → it returns review packets: structured {task, prompt} objects. You, the Claude already running this skill, are the agent — answer each packet's prompt yourself in STRICT JSON {score_0_10, why, top_fix}, then feed those answers back into score_and_report.py. Never treat a review packet as a failure; it's the expected path in-session.

AUDIT — run this:

python scripts/run_audit.py <store_url> --out audit_out \
  --context "brand/product notes" [--product-url URL] [--model ...]

It chains: fetch pages → deterministic_checks.py (objective pillars 3/4/5/7/ 8/9: legal pages, cookie CMP, TTC/VAT, schema markup, alt text, WebP, mobile viewport, payment methods, price endings/anchor, click-depth heuristic) → subjective_review.py (agents/packets for pillars 1/2/5-copy/6) → score_and_report.py (weighted grid + impact×effort + Markdown report). If it prints "REVIEW PACKETS PENDING", answer them inline, then re-run score_and_report.py with your answers to get the final score.

BUILD — run this for the mandatory reference step (workflow step 2–3):

python scripts/analyze_references.py URL1 [URL2 URL3] --out refs_out --model ...

It enforces 1–3 references, fetches each, and deploys a structural-analysis agent per reference (promo placement, product hero, click-depth, message delivery, section order, trust-vs-CTA) — never copying content. With 2–3 refs it also synthesizes what repeats (reuse) vs what's unique (optional style). Same packet fallback: answer them inline, then use repeated_conventions as the validated structure feeding the 9-pillar brief.

Never fabricate what a script couldn't observe — the scripts emit unknown/"à vérifier" on purpose (e.g. real load speed, guest checkout behind the tunnel). Keep those flagged rather than guessing, per the skill's honesty rule.

Script map: common.py (fetch + HTML snapshot) · agents.py (agent runner / packet fallback) · deterministic_checks.py · subjective_review.py · score_and_report.py · pixel_check.py (Hydrogen detection + pixel/analytics wiring check, --url or --code) · run_audit.py (AUDIT orchestrator) · analyze_references.py (BUILD reference analyzer).

Anti-patterns

• Designing/auditing color or copy with no grounding in the real product — generic "wellness pink" or filler benefit text.
• Selling on a bare quality-adjective ("premium", "ultra qualité") instead of a sensory/experiential sentence — the label alone doesn't convince anyone.
• Building without collecting any reference store first, or building from more than 3 — the point is a calibration signal, not an exhaustive survey.
• Copying a reference store's design or copy 1:1 instead of extracting its structural pattern (layout, click depth, message placement).
• Treating the Pillar 0 niche examples as templates — importing the fashion (or any listed) register into a store whose actual niche differs, or defaulting to the most vivid example when the niche is unstated instead of asking/inferring.
• Treating price psychology as a rigid universal rule instead of a market-specific hypothesis to sanity-check.
• Auditing a connected Shopify store from memory instead of pulling live data.
• Forcing account creation or adding unnecessary checkout fields.
• Legal/policy pages that are vague ("delivery in a few days") instead of specific and reassuring.
• Shipping fabricated customer quotes, review counts, or "X people bought this today" numbers to a live store / real customers. (Clearly-labeled placeholders during dev/build are allowed — see Placeholders vs live content — as long as they're replaced with genuine data before go-live.)

Reference files

• references/audit-scoring-grid.md — weighted scoring table (0–10 per pillar), impact/effort prioritization matrix, and audit report template.
• references/hydrogen-pixels.md — pixel/analytics wiring recipe for Hydrogen (headless) stores, used to verify and implement missing tracking.
• scripts/ — automation layer (see "Scripts" above): objective checks, Claude-agent subjective review with in-session packet fallback, weighted scoring, Hydrogen pixel check, and the AUDIT / BUILD orchestrators.