shopify-ai-optimizer

Open-source Claude prompt library + audit-driven rewrite logic for optimizing Shopify product catalogs for AI shopping agent visibility.

License: MIT

---

What's here

The Claude system prompts, vertical-aware guidance blocks, and the output schema we use in the AI Catalog Score Shopify app to rewrite product titles, descriptions, SEO copy, alt text, tags, and metafields in a single LLM call.

prompts/
  optimize-product.md          # Main Claude system prompt
  vertical-guidance.md         # 10 per-vertical guidance blocks
  examples/
    apparel-tshirt.json        # Input / output pair
    beauty-serum.json
    food-coffee.json
    pets-dog-food.json

schemas/
  optimize-product.json        # JSON schema for the LLM output

guards/
  pre-flight.md                # The audit-simulator check that
                               # prevents bad rewrites from shipping

---

Why these prompts work

The temptation with AI catalog rewriting is to ask Claude to "make this product better for AI agents". That produces fluffy marketing copy that doesn't move the audit score.

We do the opposite: every rewrite is steered by the audit issues. If scoreTitle is missing 2 points because the title doesn't contain the productType, the Claude prompt is conditioned on:

"The current title scored X/15. The audit flagged: productType 'Skincare' is not in the title. Generate a new title that includes 'Skincare' AND stays 30-80 characters AND keeps the brand."

Then a per-criterion pre-flight check simulates the audit on the proposed rewrite BEFORE writing to Shopify. If scoreTitle doesn't improve, the rewrite is skipped. No regressions.

Full pre-flight logic in guards/pre-flight.md.

---

Vertical-aware guidance

Different verticals have different signal vocabularies. The vertical-guidance.md doc maps each of the 10 verticals to:

• Canonical metafield keys (e.g. beauty → key_ingredient, food → ingredients, apparel → material)
• Factual markers Claude should include (ingredient lists, dimension units, certifications, skin types)
• Use-case patterns ("apply morning", "ideal for dry skin", "best for...")

So when Claude rewrites a skincare description, it knows to include ingredient names + skin-type targeting, not "premium quality" marketing.

When it rewrites a food product, it includes allergens + dietary flags. When it rewrites apparel, it includes material + fit + care.

10 verticals modeled: apparel · beauty · home · electronics · fitness · food · pets · baby · outdoor · gifts + universal fallback.

---

Output schema

Every Claude call returns JSON conforming to schemas/optimize-product.json:

{
  optimizedTitle: string;           // 30-80 chars, includes productType
  optimizedDescription: string;     // HTML, 150+ words, with bullets + h3
  suggestedTags: string[];          // 5 tags, vertical-relevant
  suggestedMetafields: Array<{
    key: string;                    // e.g. "custom.key_ingredient"
    value: string;
  }>;
  seoTitle: string;                 // <60 chars
  seoDescription: string;           // <160 chars
}

---

Use it

The reference implementation lives inside the closed Shopify app at aicatalogscore.com. What's open here:

• The prompts (prompts/) — copy verbatim into your own LLM call
• The output schema (schemas/) — use to constrain your generation
• The pre-flight logic (guards/) — port to your tool

We expect this repo to be useful to:

• Other Shopify app developers building AI optimization features
• Indie e-commerce optimization tools (Webflow, WooCommerce, etc.)
• Anyone building agentic commerce infrastructure

---

Contributing

PRs welcome for:

• New vertical guidance blocks
• Prompt improvements with measured A/B results
• Schema additions for new fields (e.g. variants, JSON-LD)
• Bug reports with reproducible inputs

See CONTRIBUTING.md.

---

Related

• agentic-catalog-scanner — the audit rubric these prompts are calibrated against (CC0)
• ai-visibility-metrics — the dataset the rubric was calibrated on (MIT)

---

Maintained by aicatalogscore.com.