Agent skill · data analytics · jeremylongshore
shopify-graphql-cost-optimizer
Master Shopify''s calculated query cost system to avoid throttling.
Why this skill is useful
Provides specific techniques and calculations for optimizing Shopify GraphQL queries that the AI wouldn't reliably generate on its own.
What it needs
Requires @shopify/shopify-api installed locally. Requires shopify account access. About 3k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
Shopify GraphQL Cost Optimizer Overview Every Shopify GraphQL query has a calculated cost. The API uses a token bucket (1,000 points max, refills at 50/second for standard plans) and throttles once depleted. The key insight: requestedQueryCost is the worst-case estimate, while actualQueryCost is what you really paid. Understanding the gap between them is how you avoid throttling. Prerequisites Shopify app with GraphQL Admin API access @shopify/shopify-api package installed Understanding of GraphQL connections (edges/node pattern) Instructions Step 1: Read Cost Headers Every GraphQL response includes cost data in extensions.cost: Add the X-GraphQL-Cost-Include-Fields: true request header for a per-field cost breakdown. Step 2: Predict Query Cost Cost rules for calculation: Single object field: 1 point (e.g., shop { name } = 1) Connection: first or last param multiplied by child cost, plus 2 for the connection itself Nested connections: costs multiply See references/cost-calculation-rules.md for the full calculation rules. Step 3: Cost Reduction Techniques Reduce first parameter — the single biggest lever: Select only needed fields — every field costs 1 point per connection node: Avoid deep nesting — flatten or split queries. See references/query-splitting.md for patterns. Step 4: Use Bulk Operations for Large Data Sets When you need 250+ items, switch to bulkOperationRunQuery. It bypasses the cost system entirely — no first/last params, no cursors, returns all items as JSONL. See references/bulk-operations.md for the complete bulkOperationRunQuery mutation, polling, and JSONL download flow. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/shopify-graphql-cost-optimizer--2a41d1