@veyralabs/skills 0.2.0 → 0.4.0

package/skills/shopify-suite/shopify-store/references/mcp-queries.md

@@ -0,0 +1,216 @@
+# MCP Queries — shopify-store Reference
+
+Ready-to-use GraphQL queries for Mode A (shopify-mcp connected).
+All queries use the Admin API via the shopify-mcp `graphql` tool.
+
+---
+
+## Products
+
+### Get all products with SEO fields
+```graphql
+query GetProducts($cursor: String) {
+  products(first: 250, after: $cursor) {
+    pageInfo { hasNextPage endCursor }
+    nodes {
+      id
+      title
+      handle
+      status
+      descriptionHtml
+      seo { title description }
+      images(first: 5) {
+        nodes { id url altText }
+      }
+      variants(first: 100) {
+        nodes { id title sku price availableForSale }
+      }
+    }
+  }
+}
+```
+
+### Products missing SEO data
+```graphql
+query ProductsSEOAudit {
+  products(first: 250, query: "status:active") {
+    nodes {
+      id
+      title
+      seo { title description }
+      images(first: 1) {
+        nodes { altText }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Collections
+
+### Full collection structure
+```graphql
+query GetCollections {
+  collections(first: 100) {
+    nodes {
+      id
+      title
+      handle
+      sortOrder
+      productsCount { count }
+      seo { title description }
+      image { altText url }
+      ruleSet {
+        rules { column relation condition }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Navigation (Menus)
+
+```graphql
+query GetMenus {
+  menus(first: 10) {
+    nodes {
+      id
+      title
+      handle
+      items {
+        id
+        title
+        url
+        type
+        items {
+          id
+          title
+          url
+          type
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Orders (last 90 days)
+
+```graphql
+query GetOrders {
+  orders(first: 250, query: "created_at:>2025-01-01") {
+    nodes {
+      id
+      totalPriceSet { shopMoney { amount currencyCode } }
+      lineItems(first: 10) {
+        nodes { quantity title sku }
+      }
+      customer { id email numberOfOrders }
+      createdAt
+      cancelledAt
+      financialStatus
+      fulfillmentStatus
+    }
+  }
+}
+```
+
+---
+
+## Metafields
+
+### Get product metafields
+```graphql
+query GetProductMetafields($id: ID!) {
+  product(id: $id) {
+    metafields(first: 20) {
+      nodes {
+        namespace
+        key
+        value
+        type
+      }
+    }
+  }
+}
+```
+
+### Set SEO metafield
+```graphql
+mutation SetMetafield($metafields: [MetafieldsSetInput!]!) {
+  metafieldsSet(metafields: $metafields) {
+    metafields { key value }
+    userErrors { field message }
+  }
+}
+```
+Variables:
+```json
+{
+  "metafields": [{
+    "ownerId": "gid://shopify/Product/123",
+    "namespace": "seo",
+    "key": "description",
+    "value": "Your SEO description here",
+    "type": "single_line_text_field"
+  }]
+}
+```
+
+---
+
+## Installed Apps (via App Installations)
+
+```graphql
+query GetInstalledApps {
+  appInstallations(first: 50) {
+    nodes {
+      app {
+        title
+        handle
+        developerName
+        pricingSummary
+      }
+      launchUrl
+      uninstallUrl
+    }
+  }
+}
+```
+
+---
+
+## Shopify Analytics (basic)
+
+```graphql
+query GetShopInfo {
+  shop {
+    name
+    myshopifyDomain
+    plan { displayName partnerDevelopment }
+    currencyCode
+    timezoneAbbreviation
+    ianaTimezone
+  }
+}
+```
+
+For revenue/conversion analytics, use the Reports API:
+```graphql
+query GetReports {
+  reports(first: 10, query: "report_type:custom") {
+    nodes {
+      id
+      name
+      category
+      shopifyQL
+    }
+  }
+}
+```

package/skills/shopify-suite/shopify-store/references/product-optimization.md

@@ -0,0 +1,266 @@
+# Product Optimization — shopify-store Reference
+
+Title formulas, description frameworks, and image standards for Shopify product pages.
+
+---
+
+## Title Formulas
+
+### Formula by product type
+
+**Apparel:**
+```
+[Product Name] — [Key Attribute] | [Brand]
+Blue Linen Shirt — Relaxed Fit | Studio Name
+Oversized Hoodie — 400gsm Cotton | Brand
+```
+
+**Electronics / tech:**
+```
+[Brand] [Product Name] [Model/Key Spec]
+Brand Wireless Headphones ANC Pro 45hr
+```
+
+**Home goods / furniture:**
+```
+[Product Name] — [Material/Style] — [Size if relevant]
+Oak Dining Table — Solid Wood — 160cm
+Linen Throw Pillow — Natural — 45x45cm
+```
+
+**Beauty / skincare:**
+```
+[Product Name] — [Key Ingredient/Benefit] | [Brand]
+Vitamin C Serum — Brightening 20% | Brand
+```
+
+**Food / consumables:**
+```
+[Product Name] — [Size/Format/Origin]
+Organic Olive Oil — 500ml Cold Press
+Colombian Coffee — Medium Roast 250g
+```
+
+### Title rules
+- 50-70 characters (shows fully in Google SERP and Shopify search)
+- Lead with product name, not brand (unless brand is the purchase driver)
+- Include the one attribute buyers filter by most (color, size, material)
+- No: "NEW", "SALE", "BEST SELLER", "!", "100% authentic"
+- No: all caps
+- No: variant info in title (size S/M/L goes in variants, not title)
+
+---
+
+## Meta Title Formulas
+
+The meta title is separate from the product title in Shopify (Admin → SEO section).
+
+```
+[Product Name] [Key Attribute] — Buy Online | [Brand]
+[Primary Keyword] — [Secondary Keyword] | [Brand]
+```
+
+Examples:
+```
+Linen Relaxed Shirt — Men's Summer Fashion | Studio Name
+Wireless Noise Cancelling Headphones | Brand
+Organic Olive Oil 500ml — Cold Pressed | Store Name
+```
+
+Rules:
+- 50-60 characters (Google truncates at ~60)
+- Include primary keyword near the front
+- Include brand at end (recognition, not keyword — separator `|` or `—`)
+- Different from the product title (if they're identical, one is wasted)
+
+---
+
+## Description Framework
+
+### SPECS → STORY → SOCIAL PROOF structure
+
+```
+[Opening line: main benefit or use case — 1 sentence]
+
+[Specs block: what it's made of, dimensions, key features — short bullets]
+
+[Story paragraph: who it's for, when to use it, why it matters — 2-3 sentences]
+
+[Trust closer: shipping, returns, sizing guide link — 1 sentence]
+```
+
+### Example (apparel)
+
+```html
+<p>A linen shirt built for warm weather — breathable, lightweight, and gets better with every wash.</p>
+
+<ul>
+  <li>100% European linen</li>
+  <li>Relaxed fit, fits true to size</li>
+  <li>Available in 8 colors</li>
+  <li>Machine washable at 30°C</li>
+</ul>
+
+<p>Designed for easy summer days — works equally well with shorts or tailored trousers. 
+The fabric softens naturally over time without losing its shape.</p>
+
+<p>Free shipping on orders over €50. 30-day free returns. <a href="/pages/size-guide">Size guide</a>.</p>
+```
+
+### Example (electronics)
+
+```html
+<p>45 hours of active noise cancellation, zero compromise on sound quality.</p>
+
+<ul>
+  <li>ANC: -35dB noise reduction</li>
+  <li>Battery: 45hr ANC on, 60hr ANC off</li>
+  <li>Charging: USB-C, 15min = 5hr playback</li>
+  <li>Connectivity: Bluetooth 5.3, multipoint (2 devices simultaneously)</li>
+  <li>Weight: 248g</li>
+</ul>
+
+<p>Designed for long work sessions and travel. The over-ear cushions are memory foam — 
+they seal out noise without pressure points after hours of wear.</p>
+
+<p>2-year warranty. Free returns within 30 days. Ships in 1-2 business days.</p>
+```
+
+### Description rules
+- Minimum 150 characters, aim for 300-500 characters
+- First 160 characters become the meta description fallback — make them strong
+- Lead with benefit, not feature ("stays cool" not "made of linen")
+- Bullets for specs, prose for story — mix formats
+- Include dimensions/weight for anything where size matters
+- No fluff: "quality product", "you'll love it", "great for everyone"
+- No generic manufacturer text — rewrite it
+
+---
+
+## Meta Description Formulas
+
+```
+[Main benefit]. [Key specs/features]. [Trust signal or CTA].
+```
+
+Examples:
+```
+Breathable linen shirt perfect for summer. Available in 8 colors, sizes XS-XXL. Free shipping over €50.
+(134 chars)
+
+Noise cancelling headphones with 45hr battery. Bluetooth 5.3, USB-C fast charge. 2-year warranty included.
+(106 chars)
+
+Cold-pressed organic olive oil from Spanish groves. 500ml bottle, harvested November 2024. Free delivery over €30.
+(113 chars)
+```
+
+Rules:
+- 120-160 characters
+- Unique per product (not the same as title)
+- Include a purchase-trigger: price signal, shipping benefit, time signal, social proof
+- No clickbait ("You won't believe...")
+- Ends with implicit CTA or benefit
+
+---
+
+## Image Standards
+
+### Required images per product
+
+| # | Image type | Purpose |
+|---|-----------|---------|
+| 1 | Hero / packshot | Main listing image — product centered, clean background |
+| 2 | Lifestyle in context | Shows scale, use, aspiration |
+| 3 | Detail / texture | Close-up of key material or feature |
+| 4+ | Variant images | One per color/style variant |
+
+### Technical specs
+
+| Spec | Recommended | Minimum |
+|------|-------------|---------|
+| Dimensions | 2048×2048px | 800×800px |
+| Format | JPEG (80-85% quality) | — |
+| Aspect ratio | 1:1 (square) | Consistent per product |
+| Background (main image) | White #FFFFFF or very light gray | Clean neutral |
+| File size | < 500KB after optimization | < 1MB |
+
+### Alt text formulas
+
+```
+Main image: [Brand] [Product Name] [Key Attribute]
+"Studio Name Blue Linen Shirt Relaxed Fit"
+
+Lifestyle: [Product Name] [Context]
+"Linen Shirt worn at outdoor dinner"
+
+Detail: [Product Name] [What the detail shows]
+"Linen Shirt fabric texture close-up"
+```
+
+Rules:
+- Describe what's in the image, not the product name repeated
+- Don't start with "Image of" or "Photo of" — Google already knows it's an image
+- Include color for variant images
+- Max 125 characters
+
+### Variant images
+
+Every color variant needs its own image — minimum the hero shot on the correct color.
+Shopify auto-switches image when customer selects a color variant if images are tagged with variant.
+
+In Shopify admin: product images → click image → assign to variant.
+
+---
+
+## Collection Descriptions
+
+Short, keyword-rich, benefit-first:
+
+```
+[What's in the collection — 1 sentence]. [Count or variety signal]. [Differentiator].
+```
+
+Examples:
+```
+Men's shirts in linen, cotton, and blends for every season. 40+ styles, new arrivals weekly. 
+Free shipping on orders over €50.
+```
+
+```
+Wireless headphones from entry-level to professional grade. Tested and reviewed by our audio team.
+30-day trial period on every model.
+```
+
+Rules:
+- 2-4 sentences
+- Include primary keyword naturally
+- Avoid "our collection of" or "we offer" — lead with what's in it
+- Update seasonally for campaign collections
+
+---
+
+## Variant Naming
+
+### Color naming
+
+Use recognizable color names, not marketing names:
+- "Navy Blue" not "Ocean Depths"
+- "Forest Green" not "Emerald Whisper"
+- "Off-White" not "Morning Mist"
+
+Exception: luxury or high-differentiation brands where color naming IS part of the brand language.
+
+### Size naming
+
+Consistent across catalog:
+- Apparel: XS, S, M, L, XL, XXL (not Extra Small, Small, etc.)
+- Shoes: numeric EU sizing (42, 43...) not US mixed
+- Home: dimensions in cm or specific names ("Small / 45×45cm")
+
+### Option order
+
+Color before size (most common filter order):
+- Option 1: Color
+- Option 2: Size
+- Option 3: Material (if needed)

package/skills/shopify-suite/shopify-store/references/seo-shopify.md

@@ -0,0 +1,165 @@
+# SEO — Shopify-Specific Issues
+
+Shopify has structural SEO issues that generic SEO guides miss. This covers the ones that actually matter.
+
+---
+
+## Duplicate Content (Shopify's biggest SEO problem)
+
+### The /products/ vs /collections/*/products/ problem
+
+Shopify serves every product at two URLs:
+- `https://store.com/products/blue-shirt`
+- `https://store.com/collections/shirts/products/blue-shirt`
+
+Shopify auto-canonicalizes collection-path URLs to the `/products/` URL. This is correct behavior — do not override it. But verify it's working:
+
+```html
+<!-- Should appear on /collections/shirts/products/blue-shirt -->
+<link rel="canonical" href="https://store.com/products/blue-shirt">
+```
+
+If a custom theme or app overrides this, you get duplicate content penalties.
+
+### Tag pages getting indexed
+
+Shopify creates URLs for every tag: `/collections/shirts/t-shirts`, `/collections/shirts/blue`.
+These are thin pages with subset content — they dilute link equity and create duplicates.
+
+Fix: add to `robots.txt` (Shopify 2.0 allows custom robots.txt):
+```
+Disallow: /collections/*+*
+```
+Or noindex via theme liquid:
+```liquid
+{% if current_tags %}
+  <meta name="robots" content="noindex, follow">
+{% endif %}
+```
+
+### Variant URLs
+
+`/products/blue-shirt?variant=123456` creates near-duplicate pages per variant.
+Shopify canonicalizes these to the main product URL automatically. Do not disable this.
+
+### Pagination
+
+`/collections/shirts?page=2` — Shopify removed `rel="next"/"prev"` pagination support in 2019. Google handles these via `?page=N` parameters. Do not noindex paginated pages — you'll lose product indexing.
+
+---
+
+## Structured Data
+
+### Product schema (must-have)
+
+Shopify themes should output this on every product page. Check if yours does:
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "Product",
+  "name": "{{ product.title }}",
+  "description": "{{ product.description | strip_html | escape }}",
+  "image": "{{ product.featured_image | img_url: '800x' }}",
+  "sku": "{{ product.selected_or_first_available_variant.sku }}",
+  "brand": {
+    "@type": "Brand",
+    "name": "{{ product.vendor }}"
+  },
+  "offers": {
+    "@type": "Offer",
+    "priceCurrency": "{{ cart.currency.iso_code }}",
+    "price": "{{ product.selected_or_first_available_variant.price | divided_by: 100.0 }}",
+    "availability": "{% if product.available %}https://schema.org/InStock{% else %}https://schema.org/OutOfStock{% endif %}",
+    "url": "{{ shop.url }}{{ product.url }}"
+  }
+  {% if product.metafields.reviews.rating %}
+  ,"aggregateRating": {
+    "@type": "AggregateRating",
+    "ratingValue": "{{ product.metafields.reviews.rating.value }}",
+    "reviewCount": "{{ product.metafields.reviews.rating_count }}"
+  }
+  {% endif %}
+}
+</script>
+```
+
+### BreadcrumbList (improves SERP appearance)
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "BreadcrumbList",
+  "itemListElement": [
+    { "@type": "ListItem", "position": 1, "name": "Home", "item": "{{ shop.url }}" },
+    { "@type": "ListItem", "position": 2, "name": "{{ collection.title }}", "item": "{{ shop.url }}{{ collection.url }}" },
+    { "@type": "ListItem", "position": 3, "name": "{{ product.title }}" }
+  ]
+}
+</script>
+```
+
+---
+
+## Title and Meta Description Formulas
+
+### Product pages
+```
+Title (50-60 chars): [Product Name] — [Key Attribute] | [Brand]
+Example: "Blue Linen Shirt — Relaxed Fit | Mariano Studio"
+
+Meta description (120-160 chars): [Benefit]. [Key features]. [CTA with differentiator].
+Example: "Breathable linen shirt perfect for summer. Available in 8 colors, sizes XS-XXL. Free shipping over €50."
+```
+
+### Collection pages
+```
+Title: [Collection Name] — [Category] | [Brand]
+Example: "Men's Shirts — Linen & Cotton | Mariano Studio"
+
+Meta description: [What's in the collection]. [Count/variety]. [Differentiator].
+Example: "Browse our collection of 40+ men's shirts in linen, cotton, and blends. New arrivals weekly. Free returns."
+```
+
+### Homepage
+```
+Title: [Brand] — [One-line value proposition]
+Example: "Mariano Studio — Sustainable Linen Clothing for Men"
+```
+
+---
+
+## Technical SEO Checklist
+
+| Issue | Check | Fix |
+|-------|-------|-----|
+| Canonical tags | View source on product + collection URL | Should point to /products/ URL |
+| Tag page indexation | Search site:store.com/collections inurl:t- | Add noindex or robots.txt disallow |
+| Duplicate H1 | Check if theme puts product title in H1 twice | One H1 per page |
+| Image alt texts | Inspect img tags on product pages | Fill via Shopify admin or bulk with metafields |
+| Page speed | PageSpeed Insights on 3 pages | Remove heavy apps, optimize images |
+| Sitemap | yourdomain.com/sitemap.xml | Should exist and include products + collections |
+| robots.txt | yourdomain.com/robots.txt | Should not block /products/ or /collections/ |
+| 404 errors | Google Search Console > Coverage | 301 redirect old URLs |
+
+---
+
+## Common Shopify SEO Mistakes
+
+**Mistake: Disabling the Shopify sitemap**
+The auto-generated sitemap at `/sitemap.xml` is good. Don't replace it with a custom one unless you have a specific reason. Many apps do this and break indexation.
+
+**Mistake: Using a page builder for all pages**
+Page builders like PageFly output custom HTML structures that often miss semantic tags (H1, structured data, canonical). Check that builder-created pages still have proper SEO markup.
+
+**Mistake: Changing product handles**
+`/products/old-handle` → `/products/new-handle` without a redirect = 404 = lost rankings.
+Shopify doesn't auto-redirect when you change a handle. Add a URL redirect in admin: Settings → Policies → URL Redirects.
+
+**Mistake: Publishing all variants as separate products**
+One product with 5 color variants is better than 5 separate products. Consolidates link equity, avoids duplicate content.
+
+**Mistake: Keeping "/a/collections/" filtering in index**
+Some filter apps create `/collections/shirts?filter.p.product_type=Formal` URLs. These should be noindexed or disallowed.