@veyralabs/skills 0.3.0 → 0.4.1

package/README.md

@@ -1,10 +1,13 @@
 # VeyraSkills
 
-Skills for Claude Code and other AI coding agents. Each skill is a plain text file that teaches your agent a specialized workflow — naming, branding, website cloning, and more.
+![7 skills](https://img.shields.io/badge/skills-7-blue) ![npm](https://img.shields.io/npm/v/@veyralabs/skills) ![license](https://img.shields.io/badge/license-MIT-green)
+
+Skills for Claude Code and other AI coding agents. Each skill is a plain text file that teaches your agent a specialized workflow - naming, branding, website cloning, Shopify development, and more.
 
 ```bash
 npx @veyralabs/skills install naming-suite
 npx @veyralabs/skills install webcloner
+npx @veyralabs/skills install shopify-suite
 ```
 
 Or install everything at once:
@@ -30,6 +33,15 @@ Four skills for naming products, auditing brands, mapping competitors, and build
 
 Works best in sequence: run `competitornames` to understand the landscape, then `domainforge` to generate names that stand out from it.
 
+### shopify-suite
+
+Two skills covering the full Shopify stack - one for developers building themes and apps, one for merchants auditing and optimizing stores.
+
+| Skill | What it does |
+|-------|-------------|
+| [shopify-dev](./skills/shopify-suite/shopify-dev/SKILL.md) | Shopify development across all layers: Liquid themes, JSON templates, app development with Remix, Storefront and Admin API, CLI workflows, checkout extensions, Hydrogen. Fetches live Shopify documentation via Context7 before answering version-sensitive questions |
+| [shopify-store](./skills/shopify-suite/shopify-store/SKILL.md) | Store audit and optimization. Works in two modes: Mode A uses shopify-mcp to read real store data (products, orders, apps, metafields); Mode B uses public extraction when MCP is not available. Audits 6 dimensions: catalog health, collection architecture, navigation, SEO, app stack, conversion signals |
+
 ### webcloner
 
 Clone any landing page, marketing site, portfolio, or ecommerce storefront into a pixel-accurate Next.js replica.
@@ -51,6 +63,9 @@ Works for landings, marketing sites, portfolios, and ecommerce product pages. No
 ```bash
 npx @veyralabs/skills install naming-suite
 npx @veyralabs/skills install webcloner
+npx @veyralabs/skills install shopify-suite
+npx @veyralabs/skills install shopify-dev
+npx @veyralabs/skills install shopify-store
 npx @veyralabs/skills install domainforge
 ```
 
@@ -109,14 +124,14 @@ npx @veyralabs/skills install domainforge
 ## Coming soon
 
 **brand-suite**
-- `brandvoice` — tone of voice guide generator
-- `brandpositioning` — positioning statement and competitive differentiation
-- `taglineforge` — tagline generation with scoring
+- `brandvoice` - tone of voice guide generator
+- `brandpositioning` - positioning statement and competitive differentiation
+- `taglineforge` - tagline generation with scoring
 
 **gtm-suite**
-- `icp` — Ideal Customer Profile builder
-- `pricingstrategy` — pricing model analysis
-- `gtmplan` — go-to-market plan generator
+- `icp` - Ideal Customer Profile builder
+- `pricingstrategy` - pricing model analysis
+- `gtmplan` - go-to-market plan generator
 
 ---
 
@@ -126,6 +141,9 @@ Each skill is also published as a standalone npm package if you only want one:
 
 - `@veyralabs/naming-suite`
 - `@veyralabs/webcloner`
+- `@veyralabs/shopify-suite`
+- `@veyralabs/shopify-dev`
+- `@veyralabs/shopify-store`
 
 ---
 

package/bin/cli.js

@@ -4,10 +4,17 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { execFileSync } = require('child_process');
 
 const SKILLS_DIR   = path.join(__dirname, '..', 'skills');
 const COMMANDS_DIR = path.join(__dirname, '..', 'commands');
 
+// pip packages required per skill
+const SKILL_PIP_DEPS = {
+  'shopify-store': ['scrapling'],
+  'webcloner':     ['scrapling'],
+};
+
 const AGENT_PATHS = {
   claude:    { local: '.claude/skills',             global: '.claude/skills' },
   cursor:    { local: '.cursor/skills',             global: '.cursor/skills' },
@@ -78,6 +85,31 @@ function copySkill(name, skillPath, dest) {
   console.log(`  ✓ ${name}`);
 }
 
+function installPipDeps(skillNames) {
+  const pkgs = [...new Set(skillNames.flatMap(n => SKILL_PIP_DEPS[n] || []))];
+  if (pkgs.length === 0) return;
+
+  let pip = null;
+  for (const cmd of ['pip3', 'pip']) {
+    try { execFileSync(cmd, ['--version'], { stdio: 'ignore' }); pip = cmd; break; } catch {}
+  }
+
+  if (!pip) {
+    console.log(`  ⚠ Python pip not found. Install manually: pip install ${pkgs.join(' ')}`);
+    return;
+  }
+
+  for (const pkg of pkgs) {
+    try {
+      console.log(`  Installing Python dependency: ${pkg}...`);
+      execFileSync(pip, ['install', pkg, '-q'], { stdio: 'inherit' });
+      console.log(`  ✓ ${pkg}`);
+    } catch {
+      console.log(`  ⚠ Failed to install ${pkg}. Run: ${pip} install ${pkg}`);
+    }
+  }
+}
+
 // Copy slash commands — Claude Code only (.claude/commands/)
 function copyCommands(agent, isGlobal) {
   if (agent !== 'claude') return;
@@ -170,6 +202,7 @@ if (command === 'install') {
   console.log(`\nInstalling into ${dest} [${agent}/${scope}]\n`);
   toInstall.forEach(name => copySkill(name, skills[name], dest));
   copyCommands(agent, isGlobal);
+  installPipDeps(toInstall);
   console.log('\nDone. Restart your agent to activate skills.\n');
   process.exit(0);
 }

package/commands/shopify-dev.md

@@ -0,0 +1,3 @@
+Activate the shopify-dev skill. Task: $ARGUMENTS
+
+Start by detecting the mode from context (theme / app / api / cli / hydrogen / debug). Fetch current Shopify documentation via Context7 before writing any code. Use the reference files in skills/shopify-suite/shopify-dev/references/ for patterns, queries, and CLI workflows.

package/commands/shopify-store.md

@@ -0,0 +1,3 @@
+Activate the shopify-store skill. Task: $ARGUMENTS
+
+Start with mode detection: attempt list_products via shopify-mcp. If MCP responds, run the full Mode A audit pipeline. If not available, switch to Mode B (public extraction via Scrapling). Use reference files in skills/shopify-suite/shopify-store/references/ for checklists, queries, and scoring.

package/install.sh

@@ -114,6 +114,37 @@ check_deps() {
   fi
 }
 
+# Skills that require Python packages: skill_name -> pip packages (space-separated)
+declare -A SKILL_PIP_DEPS=(
+  ["shopify-store"]="scrapling"
+  ["webcloner"]="scrapling"
+)
+
+install_pip_deps() {
+  local skill="$1"
+  local pkgs="${SKILL_PIP_DEPS[$skill]:-}"
+  [[ -z "$pkgs" ]] && return
+
+  local pip=""
+  for cmd in pip3 pip; do
+    command -v "$cmd" &>/dev/null && pip="$cmd" && break
+  done
+
+  if [[ -z "$pip" ]]; then
+    echo "  Warning: pip not found. Install manually: pip install $pkgs"
+    return
+  fi
+
+  for pkg in $pkgs; do
+    echo "  Installing Python dependency: $pkg..."
+    if "$pip" install "$pkg" -q; then
+      echo "  ✓ $pkg"
+    else
+      echo "  Warning: failed to install $pkg. Run: $pip install $pkg"
+    fi
+  done
+}
+
 install_skill() {
   local skill="$1"
   local dest_dir="$2"
@@ -236,11 +267,15 @@ main() {
   if [[ -n "$SKILL_NAME" ]]; then
     echo "Installing '$SKILL_NAME' → $dest/"
     install_skill "$SKILL_NAME" "$dest"
+    install_pip_deps "$SKILL_NAME"
     echo ""
     echo "Done. ${dest}/${SKILL_NAME}/ is ready."
   else
     echo "Installing all skills → $dest/"
     install_all "$dest"
+    for skill in "${!SKILL_PIP_DEPS[@]}"; do
+      install_pip_deps "$skill"
+    done
     echo ""
     echo "Done. All skills installed to ${dest}/"
   fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veyralabs/skills",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "VeyraSkills — A curated collection of Claude Code skills for founders, developers and AI builders",
   "bin": {
     "veyraskills": "bin/cli.js"
@@ -30,7 +30,12 @@
     "domain-generator",
     "startup-branding",
     "brand-strategy",
-    "developer-tools"
+    "developer-tools",
+    "shopify",
+    "shopify-theme",
+    "shopify-app",
+    "shopify-audit",
+    "ecommerce"
   ],
   "author": "VeyraLabs <hello@veyralabs.com>",
   "license": "MIT",

package/skills/shopify-suite/shopify-dev/SKILL.md

@@ -0,0 +1,409 @@
+---
+name: shopify-dev
+description: >
+  Shopify Developer. Activate when a user is building or modifying a Shopify theme, app, or integration.
+  Triggers on: "add a section to my theme", "create a Shopify app", "Shopify CLI", "Liquid template",
+  "Storefront API", "Admin API", "checkout extension", "Hydrogen", "Polaris", "shopify theme dev",
+  "metafields", "metaobjects", "app blocks", "Online Store 2.0", "section schema".
+  Covers theme development, app development, GraphQL APIs, CLI workflows, and extensions.
+---
+
+# Shopify Developer Skill
+
+You are a Shopify development expert. You know the full Shopify stack: Liquid, JSON templates, section schemas, the CLI, GraphQL Storefront and Admin APIs, Remix-based app development, Polaris, checkout extensions, and Hydrogen.
+
+Shopify's APIs and Liquid filters change every quarter. Before answering any question involving API versions, GraphQL schema, CLI flags, or new Liquid syntax — fetch current documentation via Context7 first.
+
+```
+Use context7 to get: shopify liquid documentation
+Use context7 to get: shopify storefront api graphql
+Use context7 to get: shopify admin api graphql
+Use context7 to get: shopify cli reference
+```
+
+---
+
+## Mode Detection
+
+Infer the mode from context. Ask only if genuinely ambiguous.
+
+| Mode | Triggers |
+|------|----------|
+| `theme` | Liquid, JSON templates, sections, blocks, Dawn, OS 2.0, theme editor |
+| `app` | Remix, Polaris, OAuth, webhooks, app extensions, app bridge |
+| `api` | GraphQL queries, Storefront API, Admin API, metafields |
+| `cli` | `shopify theme`, `shopify app`, deploy, environments, pull/push |
+| `hydrogen` | Headless, Remix routes, cache strategies, Storefront API |
+| `debug` | Error messages, unexpected behavior, breaking changes |
+
+---
+
+## Phase 1 — Context Fetch
+
+Before writing code, fetch current docs for the relevant area:
+
+```
+shopify liquid → for Liquid filters, tags, objects
+shopify sections → for section schema, blocks, settings
+shopify storefront api → for cart, products, collections queries
+shopify admin api → for mutations, webhooks, metafields
+shopify cli → for theme/app commands and flags
+shopify checkout extensions → for UI extensions, checkout UI
+shopify hydrogen → for headless setup, routes, caching
+```
+
+Cross-reference with `references/` files for patterns and decisions not covered by docs.
+
+---
+
+## Mode: Theme Development
+
+### JSON Template Structure (OS 2.0)
+
+```json
+{
+  "sections": {
+    "hero": {
+      "type": "hero-banner",
+      "settings": {}
+    }
+  },
+  "order": ["hero"]
+}
+```
+
+### Section Schema Pattern
+
+```liquid
+{% schema %}
+{
+  "name": "Section Name",
+  "tag": "section",
+  "class": "section-name",
+  "settings": [
+    {
+      "type": "text",
+      "id": "heading",
+      "label": "Heading",
+      "default": "Default heading"
+    },
+    {
+      "type": "image_picker",
+      "id": "image",
+      "label": "Image"
+    },
+    {
+      "type": "select",
+      "id": "layout",
+      "label": "Layout",
+      "options": [
+        { "value": "left", "label": "Left" },
+        { "value": "right", "label": "Right" }
+      ],
+      "default": "left"
+    }
+  ],
+  "blocks": [
+    {
+      "type": "feature",
+      "name": "Feature",
+      "settings": [
+        { "type": "text", "id": "title", "label": "Title" }
+      ]
+    }
+  ],
+  "max_blocks": 6,
+  "presets": [
+    {
+      "name": "Section Name"
+    }
+  ]
+}
+{% endschema %}
+```
+
+### Key Decision Points
+
+**Sections vs Blocks:**
+- Section: top-level structural element, configurable in theme editor
+- Block: repeatable element within a section (cards, features, tabs)
+- Rule: if it repeats, it's a block; if it's a layout region, it's a section
+
+**Metafields vs Metaobjects:**
+- Metafield: extra data attached to existing resource (product, collection, page)
+- Metaobject: standalone structured content type (team members, testimonials, FAQs)
+- Rule: if it belongs TO something → metafield; if it IS something on its own → metaobject
+
+**Section Rendering API:**
+Use for partial updates without full page reload:
+```javascript
+fetch(`?section_id=cart-items`)
+  .then(r => r.text())
+  .then(html => {
+    document.querySelector('#cart-items').innerHTML =
+      new DOMParser()
+        .parseFromString(html, 'text/html')
+        .querySelector('#cart-items').innerHTML;
+  });
+```
+
+### AJAX Cart Pattern
+
+```javascript
+async function addToCart(variantId, quantity = 1) {
+  const res = await fetch('/cart/add.js', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ id: variantId, quantity }),
+  });
+  if (!res.ok) throw new Error('Add to cart failed');
+  return res.json();
+}
+
+async function getCart() {
+  return fetch('/cart.js').then(r => r.json());
+}
+
+async function updateCart(updates) {
+  return fetch('/cart/update.js', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ updates }),
+  }).then(r => r.json());
+}
+```
+
+---
+
+## Mode: App Development
+
+### Stack (2025+)
+
+New Shopify apps use the **Dev Dashboard** (not Partner Dashboard). All new apps use OAuth client credentials, not static access tokens.
+
+```bash
+npm init @shopify/app@latest
+# Choose: Remix template
+```
+
+### App Structure
+
+```
+app/
+  routes/
+    app._index.tsx          ← main app page
+    app.products.tsx        ← products page
+    webhooks.tsx            ← webhook handler
+  shopify.server.ts         ← Shopify auth + API client
+  db.server.ts              ← Prisma DB
+```
+
+### Admin API Call in Remix
+
+```typescript
+// app/routes/app._index.tsx
+import { json } from "@remix-run/node";
+import { useLoaderData } from "@remix-run/react";
+import { authenticate } from "../shopify.server";
+
+export const loader = async ({ request }) => {
+  const { admin } = await authenticate.admin(request);
+
+  const response = await admin.graphql(`
+    query {
+      products(first: 10) {
+        nodes {
+          id
+          title
+          status
+        }
+      }
+    }
+  `);
+
+  const { data } = await response.json();
+  return json({ products: data.products.nodes });
+};
+```
+
+### Webhook Handler
+
+```typescript
+// app/routes/webhooks.tsx
+import { authenticate } from "../shopify.server";
+import db from "../db.server";
+
+export const action = async ({ request }) => {
+  const { topic, shop, session, payload } = await authenticate.webhook(request);
+
+  switch (topic) {
+    case "PRODUCTS_UPDATE":
+      await db.product.upsert({
+        where: { shopifyId: payload.id.toString() },
+        update: { title: payload.title },
+        create: { shopifyId: payload.id.toString(), title: payload.title, shop },
+      });
+      break;
+
+    case "APP_UNINSTALLED":
+      if (session) await db.session.deleteMany({ where: { shop } });
+      break;
+  }
+
+  return new Response();
+};
+```
+
+### Polaris Component Rules
+
+- Always import from `@shopify/polaris`
+- Wrap app in `<AppProvider i18n={translations}>` at root
+- Use `Page` + `Layout` + `Card` structure for all pages
+- `ResourceList` for lists of items, `DataTable` for tabular data
+- `useAppBridge` for redirect and toast
+
+---
+
+## Mode: Extensions
+
+### Checkout UI Extension
+
+```typescript
+// extensions/checkout-ui/src/Checkout.tsx
+import {
+  reactExtension,
+  useDeliveryGroups,
+  Banner,
+  BlockStack,
+  Text,
+} from "@shopify/ui-extensions-react/checkout";
+
+export default reactExtension("purchase.checkout.block.render", () => (
+  <Extension />
+));
+
+function Extension() {
+  const deliveryGroups = useDeliveryGroups();
+
+  return (
+    <BlockStack>
+      <Banner title="Delivery info">
+        <Text>Your order ships in 2-3 business days.</Text>
+      </Banner>
+    </BlockStack>
+  );
+}
+```
+
+Extension targets — common ones:
+- `purchase.checkout.block.render` — block anywhere in checkout
+- `purchase.checkout.shipping-option-list.render-after` — after shipping options
+- `purchase.checkout.payment-method-list.render-after` — after payment methods
+- `purchase.thank-you.block.render` — thank you page
+
+---
+
+## Mode: Hydrogen (Headless)
+
+### Route Pattern
+
+```typescript
+// app/routes/products.$handle.tsx
+import { LoaderFunctionArgs } from "@remix-run/node";
+import { useLoaderData } from "@remix-run/react";
+import { getPaginationVariables } from "@shopify/hydrogen";
+
+export async function loader({ params, context, request }: LoaderFunctionArgs) {
+  const { handle } = params;
+
+  const { product } = await context.storefront.query(PRODUCT_QUERY, {
+    variables: { handle },
+    cache: context.storefront.CacheLong(),  // cache strategy
+  });
+
+  if (!product) throw new Response(null, { status: 404 });
+  return { product };
+}
+
+const PRODUCT_QUERY = `#graphql
+  query Product($handle: String!) {
+    product(handle: $handle) {
+      id
+      title
+      handle
+      description
+      priceRange {
+        minVariantPrice { amount currencyCode }
+      }
+      images(first: 10) {
+        nodes { id url altText width height }
+      }
+      variants(first: 100) {
+        nodes {
+          id
+          title
+          availableForSale
+          price { amount currencyCode }
+          selectedOptions { name value }
+        }
+      }
+    }
+  }
+` as const;
+```
+
+### Cache Strategies
+
+```typescript
+context.storefront.CacheNone()       // no cache — dynamic, personalized
+context.storefront.CacheShort()      // 1min — semi-dynamic (cart, recently viewed)
+context.storefront.CacheLong()       // 1hr — mostly static (product pages)
+context.storefront.CacheCustom({ maxAge: 3600, staleWhileRevalidate: 82800 })
+```
+
+---
+
+## Debug Mode
+
+When debugging Shopify issues, always:
+
+1. Check the API version in `shopify.server.ts` — Shopify deprecates quarterly
+2. Verify scopes match what the operation requires
+3. Check if the feature requires a specific Shopify plan
+4. Look for `userErrors` in mutations — GraphQL returns 200 even on business errors:
+
+```graphql
+mutation {
+  productUpdate(input: { id: $id, title: $title }) {
+    product { id }
+    userErrors {       # ← always check this
+      field
+      message
+    }
+  }
+}
+```
+
+5. Theme errors: check the Shopify admin → Themes → Edit code → inspect the error output
+
+---
+
+## Anti-Patterns
+
+**Don't hardcode API versions.** Read from `shopify.server.ts` config and update quarterly.
+
+**Don't use `accessToken` directly in frontend.** Storefront API token is public-safe; Admin API token never goes to client.
+
+**Don't skip `userErrors` in mutations.** GraphQL Admin API returns HTTP 200 even when the operation fails at the business logic level.
+
+**Don't use `window.location` in app routes.** Use `redirect()` from Remix or `useNavigate()`.
+
+**Don't create sections without `presets`.** Without presets, the section won't appear in the theme editor's "Add section" menu.
+
+---
+
+Reference files:
+- `references/liquid-patterns.md` — Liquid syntax, filters, objects, gotchas
+- `references/graphql-queries.md` — ready-to-use Storefront + Admin API queries
+- `references/cli-workflows.md` — CLI commands, environments, deploy flows
+- `references/app-architecture.md` — app structure decisions, auth, billing