shopify-starter-kit 1.0.0

package/.agent/skills/shopify-apps/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: shopify-apps
+description: "Expert patterns for Shopify app development including Remix/React Router apps, embedded apps with App Bridge, webhook handling, GraphQL Admin API, Polaris components, billing, and app extensions. U..."
+risk: unknown
+source: "vibeship-spawner-skills (Apache 2.0)"
+date_added: "2026-02-27"
+---
+
+# Shopify Apps
+
+## Patterns
+
+### React Router App Setup
+
+Modern Shopify app template with React Router
+
+### Embedded App with App Bridge
+
+Render app embedded in Shopify Admin
+
+### Webhook Handling
+
+Secure webhook processing with HMAC verification
+
+## Anti-Patterns
+
+### ❌ REST API for New Apps
+
+### ❌ Webhook Processing Before Response
+
+### ❌ Polling Instead of Webhooks
+
+## ⚠️ Sharp Edges
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| Issue | high | ## Respond immediately, process asynchronously |
+| Issue | high | ## Check rate limit headers |
+| Issue | high | ## Request protected customer data access |
+| Issue | medium | ## Use TOML only (recommended) |
+| Issue | medium | ## Handle both URL formats |
+| Issue | high | ## Use GraphQL for all new code |
+| Issue | high | ## Use latest App Bridge via script tag |
+| Issue | high | ## Implement all GDPR handlers |
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/.agent/skills/shopify-automation/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: shopify-automation
+description: "Automate Shopify tasks via Rube MCP (Composio): products, orders, customers, inventory, collections. Always search tools first for current schemas."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Shopify Automation via Rube MCP
+
+Automate Shopify operations through Composio's Shopify toolkit via Rube MCP.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active Shopify connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `shopify`
+- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
+
+## Setup
+
+**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
+
+
+1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
+2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `shopify`
+3. If connection is not ACTIVE, follow the returned auth link to complete Shopify OAuth
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. Manage Products
+
+**When to use**: User wants to list, search, create, or manage products
+
+**Tool sequence**:
+1. `SHOPIFY_GET_PRODUCTS` / `SHOPIFY_GET_PRODUCTS_PAGINATED` - List products [Optional]
+2. `SHOPIFY_GET_PRODUCT` - Get single product details [Optional]
+3. `SHOPIFY_BULK_CREATE_PRODUCTS` - Create products in bulk [Optional]
+4. `SHOPIFY_GET_PRODUCTS_COUNT` - Get product count [Optional]
+
+**Key parameters**:
+- `product_id`: Product ID for single retrieval
+- `title`: Product title
+- `vendor`: Product vendor
+- `status`: 'active', 'draft', or 'archived'
+
+**Pitfalls**:
+- Paginated results require cursor-based pagination for large catalogs
+- Product variants are nested within the product object
+
+### 2. Manage Orders
+
+**When to use**: User wants to list, search, or inspect orders
+
+**Tool sequence**:
+1. `SHOPIFY_GET_ORDERS_WITH_FILTERS` - List orders with filters [Required]
+2. `SHOPIFY_GET_ORDER` - Get single order details [Optional]
+3. `SHOPIFY_GET_FULFILLMENT` - Get fulfillment details [Optional]
+4. `SHOPIFY_GET_FULFILLMENT_EVENTS` - Track fulfillment events [Optional]
+
+**Key parameters**:
+- `status`: Order status filter ('any', 'open', 'closed', 'cancelled')
+- `financial_status`: Payment status filter
+- `fulfillment_status`: Fulfillment status filter
+- `order_id`: Order ID for single retrieval
+- `created_at_min`/`created_at_max`: Date range filters
+
+**Pitfalls**:
+- Order IDs are numeric; use string format for API calls
+- Default order listing may not include all statuses; specify 'any' for all
+
+### 3. Manage Customers
+
+**When to use**: User wants to list or search customers
+
+**Tool sequence**:
+1. `SHOPIFY_GET_ALL_CUSTOMERS` - List all customers [Required]
+
+**Key parameters**:
+- `limit`: Number of customers per page
+- `since_id`: Pagination cursor
+
+**Pitfalls**:
+- Customer data includes order count and total spent
+- Large customer lists require pagination
+
+### 4. Manage Collections
+
+**When to use**: User wants to manage product collections
+
+**Tool sequence**:
+1. `SHOPIFY_GET_SMART_COLLECTIONS` - List smart collections [Optional]
+2. `SHOPIFY_GET_SMART_COLLECTION_BY_ID` - Get collection details [Optional]
+3. `SHOPIFY_CREATE_SMART_COLLECTIONS` - Create a smart collection [Optional]
+4. `SHOPIFY_ADD_PRODUCT_TO_COLLECTION` - Add product to collection [Optional]
+5. `SHOPIFY_GET_PRODUCTS_IN_COLLECTION` - List products in collection [Optional]
+
+**Key parameters**:
+- `collection_id`: Collection ID
+- `product_id`: Product ID for adding to collection
+- `rules`: Smart collection rules for automatic inclusion
+
+**Pitfalls**:
+- Smart collections auto-populate based on rules; manual collections use custom collections API
+- Collection count endpoints provide approximate counts
+
+### 5. Manage Inventory
+
+**When to use**: User wants to check or manage inventory levels
+
+**Tool sequence**:
+1. `SHOPIFY_GET_INVENTORY_LEVELS` / `SHOPIFY_RETRIEVES_A_LIST_OF_INVENTORY_LEVELS` - Check stock [Required]
+2. `SHOPIFY_LIST_LOCATION` - List store locations [Optional]
+
+**Key parameters**:
+- `inventory_item_ids`: Inventory item IDs to check
+- `location_ids`: Location IDs to filter by
+
+**Pitfalls**:
+- Inventory is tracked per variant per location
+- Location IDs are required for multi-location stores
+
+## Common Patterns
+
+### Pagination
+
+- Use `limit` and `page_info` cursor for paginated results
+- Check response for `next` link header
+- Continue until no more pages available
+
+### GraphQL Queries
+
+For advanced operations:
+```
+1. Call SHOPIFY_GRAPH_QL_QUERY with custom query
+2. Parse response from data object
+```
+
+## Known Pitfalls
+
+**API Versioning**:
+- Shopify REST API has versioned endpoints
+- Some features require specific API versions
+
+**Rate Limits**:
+- REST API: 2 requests/second for standard plans
+- GraphQL: 1000 cost points per second
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| List products | SHOPIFY_GET_PRODUCTS | (filters) |
+| Get product | SHOPIFY_GET_PRODUCT | product_id |
+| Products paginated | SHOPIFY_GET_PRODUCTS_PAGINATED | limit, page_info |
+| Bulk create | SHOPIFY_BULK_CREATE_PRODUCTS | products |
+| Product count | SHOPIFY_GET_PRODUCTS_COUNT | (none) |
+| List orders | SHOPIFY_GET_ORDERS_WITH_FILTERS | status, financial_status |
+| Get order | SHOPIFY_GET_ORDER | order_id |
+| List customers | SHOPIFY_GET_ALL_CUSTOMERS | limit |
+| Shop details | SHOPIFY_GET_SHOP_DETAILS | (none) |
+| Validate access | SHOPIFY_VALIDATE_ACCESS | (none) |
+| Smart collections | SHOPIFY_GET_SMART_COLLECTIONS | (none) |
+| Products in collection | SHOPIFY_GET_PRODUCTS_IN_COLLECTION | collection_id |
+| Inventory levels | SHOPIFY_GET_INVENTORY_LEVELS | inventory_item_ids |
+| Locations | SHOPIFY_LIST_LOCATION | (none) |
+| Fulfillment | SHOPIFY_GET_FULFILLMENT | order_id, fulfillment_id |
+| GraphQL | SHOPIFY_GRAPH_QL_QUERY | query |
+| Bulk query | SHOPIFY_BULK_QUERY_OPERATION | query |
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/.agent/skills/shopify-development/README.md

@@ -0,0 +1,60 @@
+# Shopify Development Skill
+
+Comprehensive skill for building on Shopify platform: apps, extensions, themes, and API integrations.
+
+## Features
+
+- **App Development** - OAuth authentication, GraphQL Admin API, webhooks, billing integration
+- **UI Extensions** - Checkout, Admin, POS customizations with Polaris components
+- **Theme Development** - Liquid templating, sections, snippets
+- **Shopify Functions** - Custom discounts, payment, delivery rules
+
+## Structure
+
+```
+shopify-development/
+├── SKILL.md              # Main skill file (AI-optimized)
+├── README.md             # This file
+├── references/
+│   ├── app-development.md    # OAuth, API, webhooks, billing
+│   ├── extensions.md         # UI extensions, Functions
+│   └── themes.md             # Liquid, theme architecture
+└── scripts/
+    ├── shopify_init.py       # Interactive project scaffolding
+    ├── shopify_graphql.py    # GraphQL utilities & templates
+    └── tests/                # Unit tests
+```
+
+## Validated GraphQL
+
+All GraphQL queries and mutations in this skill have been validated against Shopify Admin API 2026-01 schema using the official Shopify MCP.
+
+## Quick Start
+
+```bash
+# Install Shopify CLI
+npm install -g @shopify/cli@latest
+
+# Create new app
+shopify app init
+
+# Start development
+shopify app dev
+```
+
+## Usage Triggers
+
+This skill activates when the user mentions:
+
+- "shopify app", "shopify extension", "shopify theme"
+- "checkout extension", "admin extension", "POS extension"
+- "liquid template", "polaris", "shopify graphql"
+- "shopify webhook", "shopify billing", "metafields"
+
+## API Version
+
+Current: **2026-01** (Quarterly releases with 12-month support)
+
+## License
+
+MIT

package/.agent/skills/shopify-development/SKILL.md

@@ -0,0 +1,368 @@
+---
+name: shopify-development
+description: Build Shopify apps, extensions, themes using GraphQL Admin API, Shopify CLI, Polaris UI, and Liquid.
+risk: unknown
+source: community
+date_added: '2026-02-27'
+---
+
+# Shopify Development Skill
+
+Use this skill when the user asks about:
+
+- Building Shopify apps or extensions
+- Creating checkout/admin/POS UI customizations
+- Developing themes with Liquid templating
+- Integrating with Shopify GraphQL or REST APIs
+- Implementing webhooks or billing
+- Working with metafields or Shopify Functions
+
+---
+
+## ROUTING: What to Build
+
+**IF user wants to integrate external services OR build merchant tools OR charge for features:**
+→ Build an **App** (see `references/app-development.md`)
+
+**IF user wants to customize checkout OR add admin UI OR create POS actions OR implement discount rules:**
+→ Build an **Extension** (see `references/extensions.md`)
+
+**IF user wants to customize storefront design OR modify product/collection pages:**
+→ Build a **Theme** (see `references/themes.md`)
+
+**IF user needs both backend logic AND storefront UI:**
+→ Build **App + Theme Extension** combination
+
+---
+
+## Shopify CLI Commands
+
+Install CLI:
+
+```bash
+npm install -g @shopify/cli@latest
+```
+
+Create and run app:
+
+```bash
+shopify app init          # Create new app
+shopify app dev           # Start dev server with tunnel
+shopify app deploy        # Build and upload to Shopify
+```
+
+Generate extension:
+
+```bash
+shopify app generate extension --type checkout_ui_extension
+shopify app generate extension --type admin_action
+shopify app generate extension --type admin_block
+shopify app generate extension --type pos_ui_extension
+shopify app generate extension --type function
+```
+
+Theme development:
+
+```bash
+shopify theme init        # Create new theme
+shopify theme dev         # Start local preview at localhost:9292
+shopify theme pull --live # Pull live theme
+shopify theme push --development  # Push to dev theme
+```
+
+---
+
+## Access Scopes
+
+Configure in `shopify.app.toml`:
+
+```toml
+[access_scopes]
+scopes = "read_products,write_products,read_orders,write_orders,read_customers"
+```
+
+Common scopes:
+
+- `read_products`, `write_products` - Product catalog access
+- `read_orders`, `write_orders` - Order management
+- `read_customers`, `write_customers` - Customer data
+- `read_inventory`, `write_inventory` - Stock levels
+- `read_fulfillments`, `write_fulfillments` - Order fulfillment
+
+---
+
+## GraphQL Patterns (Validated against API 2026-01)
+
+### Query Products
+
+```graphql
+query GetProducts($first: Int!, $query: String) {
+  products(first: $first, query: $query) {
+    edges {
+      node {
+        id
+        title
+        handle
+        status
+        variants(first: 5) {
+          edges {
+            node {
+              id
+              price
+              inventoryQuantity
+            }
+          }
+        }
+      }
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+  }
+}
+```
+
+### Query Orders
+
+```graphql
+query GetOrders($first: Int!) {
+  orders(first: $first) {
+    edges {
+      node {
+        id
+        name
+        createdAt
+        displayFinancialStatus
+        totalPriceSet {
+          shopMoney {
+            amount
+            currencyCode
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Set Metafields
+
+```graphql
+mutation SetMetafields($metafields: [MetafieldsSetInput!]!) {
+  metafieldsSet(metafields: $metafields) {
+    metafields {
+      id
+      namespace
+      key
+      value
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+
+Variables example:
+
+```json
+{
+  "metafields": [
+    {
+      "ownerId": "gid://shopify/Product/123",
+      "namespace": "custom",
+      "key": "care_instructions",
+      "value": "Handle with care",
+      "type": "single_line_text_field"
+    }
+  ]
+}
+```
+
+---
+
+## Checkout Extension Example
+
+```tsx
+import {
+  reactExtension,
+  BlockStack,
+  TextField,
+  Checkbox,
+  useApplyAttributeChange,
+} from "@shopify/ui-extensions-react/checkout";
+
+export default reactExtension("purchase.checkout.block.render", () => (
+  <GiftMessage />
+));
+
+function GiftMessage() {
+  const [isGift, setIsGift] = useState(false);
+  const [message, setMessage] = useState("");
+  const applyAttributeChange = useApplyAttributeChange();
+
+  useEffect(() => {
+    if (isGift && message) {
+      applyAttributeChange({
+        type: "updateAttribute",
+        key: "gift_message",
+        value: message,
+      });
+    }
+  }, [isGift, message]);
+
+  return (
+    <BlockStack spacing="loose">
+      <Checkbox checked={isGift} onChange={setIsGift}>
+        This is a gift
+      </Checkbox>
+      {isGift && (
+        <TextField
+          label="Gift Message"
+          value={message}
+          onChange={setMessage}
+          multiline={3}
+        />
+      )}
+    </BlockStack>
+  );
+}
+```
+
+---
+
+## Liquid Template Example
+
+```liquid
+{% comment %} Product Card Snippet {% endcomment %}
+<div class="product-card">
+  <a href="{{ product.url }}">
+    {% if product.featured_image %}
+      <img
+        src="{{ product.featured_image | img_url: 'medium' }}"
+        alt="{{ product.title | escape }}"
+        loading="lazy"
+      >
+    {% endif %}
+    <h3>{{ product.title }}</h3>
+    <p class="price">{{ product.price | money }}</p>
+    {% if product.compare_at_price > product.price %}
+      <p class="sale-badge">Sale</p>
+    {% endif %}
+  </a>
+</div>
+```
+
+---
+
+## Webhook Configuration
+
+In `shopify.app.toml`:
+
+```toml
+[webhooks]
+api_version = "2026-01"
+
+[[webhooks.subscriptions]]
+topics = ["orders/create", "orders/updated"]
+uri = "/webhooks/orders"
+
+[[webhooks.subscriptions]]
+topics = ["products/update"]
+uri = "/webhooks/products"
+
+# GDPR mandatory webhooks (required for app approval)
+[webhooks.privacy_compliance]
+customer_data_request_url = "/webhooks/gdpr/data-request"
+customer_deletion_url = "/webhooks/gdpr/customer-deletion"
+shop_deletion_url = "/webhooks/gdpr/shop-deletion"
+```
+
+---
+
+## Best Practices
+
+### API Usage
+
+- Use GraphQL over REST for new development
+- Request only fields you need (reduces query cost)
+- Implement cursor-based pagination with `pageInfo.endCursor`
+- Use bulk operations for processing more than 250 items
+- Handle rate limits with exponential backoff
+
+### Security
+
+- Store API credentials in environment variables
+- Always verify webhook HMAC signatures before processing
+- Validate OAuth state parameter to prevent CSRF
+- Request minimal access scopes
+- Use session tokens for embedded apps
+
+### Performance
+
+- Cache API responses when data doesn't change frequently
+- Use lazy loading in extensions
+- Optimize images in themes using `img_url` filter
+- Monitor GraphQL query costs via response headers
+
+---
+
+## Troubleshooting
+
+**IF you see rate limit errors:**
+→ Implement exponential backoff retry logic
+→ Switch to bulk operations for large datasets
+→ Monitor `X-Shopify-Shop-Api-Call-Limit` header
+
+**IF authentication fails:**
+→ Verify the access token is still valid
+→ Check that all required scopes were granted
+→ Ensure OAuth flow completed successfully
+
+**IF extension is not appearing:**
+→ Verify the extension target is correct
+→ Check that extension is published via `shopify app deploy`
+→ Confirm the app is installed on the test store
+
+**IF webhook is not receiving events:**
+→ Verify the webhook URL is publicly accessible
+→ Check HMAC signature validation logic
+→ Review webhook logs in Partner Dashboard
+
+**IF GraphQL query fails:**
+→ Validate query against schema (use GraphiQL explorer)
+→ Check for deprecated fields in error message
+→ Verify you have required access scopes
+
+---
+
+## Reference Files
+
+For detailed implementation guides, read these files:
+
+- `references/app-development.md` - OAuth authentication flow, GraphQL mutations for products/orders/billing, webhook handlers, billing API integration
+- `references/extensions.md` - Checkout UI components, Admin UI extensions, POS extensions, Shopify Functions for discounts/payment/delivery
+- `references/themes.md` - Liquid syntax reference, theme directory structure, sections and snippets, common patterns
+
+---
+
+## Scripts
+
+- `scripts/shopify_init.py` - Interactive project scaffolding. Run: `python scripts/shopify_init.py`
+- `scripts/shopify_graphql.py` - GraphQL utilities with query templates, pagination, rate limiting. Import: `from shopify_graphql import ShopifyGraphQL`
+
+---
+
+## Official Documentation Links
+
+- Shopify Developer Docs: https://shopify.dev/docs
+- GraphQL Admin API Reference: https://shopify.dev/docs/api/admin-graphql
+- Shopify CLI Reference: https://shopify.dev/docs/api/shopify-cli
+- Polaris Design System: https://polaris.shopify.com
+
+API Version: 2026-01 (quarterly releases, 12-month deprecation window)
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.