New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Shopify Known Pitfalls

by jeremylongshore in jeremylongshore/tons-of-skills-marketplace

Identify and avoid Shopify API anti-patterns: ignoring userErrors, wrong API version, REST instead of GraphQL, missing GDPR webhooks, and webhook timeout issues.

MITAuto-check passedBackend & APIs

Install Shopify Known Pitfalls

skills CLI
$ npx skills add jeremylongshore/tons-of-skills-marketplace --skill shopify-known-pitfalls -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install jeremylongshore/tons-of-skills-marketplace shopify-known-pitfalls --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/jeremylongshore/tons-of-skills-marketplace.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/.curated/shopify-known-pitfalls .claude/skills/shopify-known-pitfalls && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
shopify-known-pitfalls
GitHub stars
2.8k
Token cost
~1.4k tokens
SKILL.md length
602 words
Files
3 (incl. references)
Skills in repo
3,342
Repo updated
First seen
Licence
MIT

At a glance

Identify and avoid Shopify API anti-patterns: ignoring userErrors, wrong API version, REST instead of GraphQL, missing GDPR webhooks, and webhook timeout issues.

  • Reviewing a Shopify codebase
  • SKILL.md covers Overview, Prerequisites, Instructions and Output, plus 4 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
  • Preparing for App Store submission

What it does

Shopify Known Pitfalls is an agent skill from jeremylongshore/tons-of-skills-marketplace. Identify and avoid Shopify API anti-patterns: ignoring userErrors, wrong API version, REST instead of GraphQL, missing GDPR webhooks, and webhook timeout issues. Use when reviewing a Shopify codebase, preparing for App Store submission, or debugging mysterious API failures. Trigger with phrases like "shopify mistakes", "shopify anti-patterns", "shopify pitfalls", "shopify what not to do", "shopify code review".

Its SKILL.md is about 1.4k tokens, which your agent loads only when the skill is triggered. The skill folder holds 3 other files, including reference files (for example `references/pitfall-examples.md` and `references/pitfall-scan-script.md`). Compatibility notes: Designed for Claude Code

It sits in Backend & APIs, covering Webhooks, GraphQL and Privacy and GDPR. It works with Shopify and GraphQL. The repository describes itself as: Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com. The licence is MIT.

When your agent uses it

  • Reviewing a Shopify codebase
  • Preparing for App Store submission
  • Debugging mysterious API failures
  • With phrases like shopify mistakes

Example prompts

  • “shopify mistakes”
  • “shopify anti-patterns”
  • “shopify pitfalls”
  • “/shopify-known-pitfalls”

Requirements

  • Compatibility (from SKILL.md): Designed for Claude Code
  • Pre-approved tools (allowed-tools): Read, Grep

What it can do on your machine

Read from SKILL.md and the folder at commit cfae287. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Read
    • Grep

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • shopify.dev

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

  • Compatibility

    Designed for Claude Code

    From compatibility in the SKILL.md frontmatter.

Context cost

Shopify Known Pitfalls loads about 1.4k tokens when it runs, and up to ~3.2k if it reads all its reference files. Until then it costs about 109 tokens; SKILL.md has 602 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~109
When it runs · the whole SKILL.md, loaded when a task matches
~1.4k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~3.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from jeremylongshore/tons-of-skills-marketplace at commit cfae287, republished under its MIT licence (© jeremylongshore). 602 words, ~1,413 tokens.

Download SKILL.mdSave it as .claude/skills/shopify-known-pitfalls/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.
name
shopify-known-pitfalls
description
Identify and avoid Shopify API anti-patterns: ignoring userErrors, wrong API version, REST instead of GraphQL, missing GDPR webhooks, and webhook timeout issues. Use when reviewing a Shopify codebase, preparing for App Store submission, or debugging mysterious API failures. Trigger with phrases like "shopify mistakes", "shopify anti-patterns", "shopify pitfalls", "shopify what not to do", "shopify code review".
allowed-tools
Read, Grep
compatibility
Designed for Claude Code
version
2.7.0
license
MIT
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
saas, ecommerce, shopify

Shopify Known Pitfalls

Overview

The 10 most common mistakes when building Shopify apps, with real API examples showing the wrong way and the right way.

Prerequisites

  • Existing Shopify app codebase to review or audit
  • Familiarity with GraphQL Admin API query patterns and response shapes
  • Access scopes configured for the APIs your app uses
  • @shopify/shopify-api v9+ installed (for code examples)

Instructions

Each pitfall includes a wrong-way and right-way code example. See Pitfall Examples for all 10 complete code comparisons.

Pitfall #1: Not Checking userErrors (The #1 Mistake)

Shopify GraphQL mutations return HTTP 200 even when they fail. The errors are in userErrors. Always check userErrors.length > 0 before accessing the result.

Pitfall #2: Using REST When GraphQL Is Required

REST Admin API is legacy as of October 2024. New public apps after April 2025 must use GraphQL. GraphQL also lets you request only the fields you need.

Pitfall #3: Ignoring API Version Deprecation

Shopify deprecates API versions ~12 months after release. Use LATEST_API_VERSION from @shopify/shopify-api and monitor x-shopify-api-deprecated-reason response headers.

Pitfall #4: Missing Mandatory GDPR Webhooks

Your app will be rejected from the App Store without customers/data_request, customers/redact, and shop/redact webhook handlers.

Pitfall #5: Webhook Handler Takes Too Long

Shopify expects a 200 response within 5 seconds. Respond immediately and queue work asynchronously, otherwise Shopify retries and creates duplicates.

Pitfall #6: Using ProductInput on API 2024-10+

The ProductInput type was split into ProductCreateInput and ProductUpdateInput in 2024-10. Use the specific type for each operation.

Pitfall #7: Not Using Cursor Pagination

Shopify uses Relay-style cursor pagination, not page numbers. Use after / endCursor with pageInfo.

Pitfall #8: Requesting 250 Items Per Page

first: 250 with nested connections creates enormous query costs that THROTTLE immediately. Use first: 50 or smaller with nested resources.

Pitfall #9: Exposing Admin Token in Client-Side Code

Admin API tokens have full access. Never send them to the browser — proxy through your server.

Pitfall #10: Not Handling APP_UNINSTALLED Webhook

When a merchant uninstalls your app, clean up sessions immediately. Stale sessions cause auth redirect loops on reinstall.

Output

  • Anti-patterns identified in codebase
  • Fixes prioritized (security first, then correctness)
  • Prevention measures in place (linting, CI checks)
Show full SKILL.md (248 more words)Show less

Error Handling

PitfallHow to DetectPrevention
Missing userErrors checkNull pointer crashesESLint rule or wrapper function
REST usagegrep -r "clients.Rest" src/Migration guide + lint rule
Old API versiongrep -r "apiVersion" src/CI check against supported versions
Missing GDPR webhooksApp Store rejectionPre-submit compliance checker
Webhook timeoutShopify retry stormsQueue-based processing
ProductInput on 2024-10GraphQL type errorUpdate mutations
Page-based paginationQuery errorsUse cursor pagination pattern
first: 250THROTTLED responsesQuery cost budgets
Admin token in clientSecurity auditServer-side proxy
No APP_UNINSTALLEDAuth loops on reinstallWebhook handler + session cleanup

Examples

Quick Pitfall Scan

Run automated detection against your Shopify codebase to find REST usage, missing userErrors checks, old API versions, hardcoded tokens, and oversized page requests.

See Pitfall Scan Script for the complete scan script.

Resources

Quick Reference Card

PitfallDetectionFix
No userErrors checkNull crashes on mutationsAlways check userErrors.length > 0
REST instead of GraphQLgrep "clients.Rest"Migrate to clients.Graphql
Old API versiongrep "2023-"Use LATEST_API_VERSION from SDK
Missing GDPR webhooksApp Store rejectionAdd 3 mandatory webhook handlers
Webhook timeoutRetry storms, duplicatesRespond 200 immediately, queue processing
ProductInput on 2024-10Type errorUse ProductCreateInput / ProductUpdateInput
Page-number paginationQuery errorsUse cursor-based with pageInfo
first: 250 with nestingTHROTTLEDUse first: 50 or smaller
Admin token in browserSecurity scanServer-side proxy only
No APP_UNINSTALLEDAuth loop on reinstallClean up sessions on uninstall

© jeremylongshore, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files (references) in skills/.curated/shopify-known-pitfalls of jeremylongshore/tons-of-skills-marketplace.

  • SKILL.md
  • references/pitfall-examples.md
  • references/pitfall-scan-script.md

Open the folder on GitHubat commit cfae287

Compare with similar skills

Shopify Known Pitfalls next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Shopify Known Pitfalls compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Shopify Known Pitfalls this skilljeremylongshore/tons-of-skills-marketplace2.8k—~1.4kAutomated safety check: PassMIT
ShopifyShopify/Shopify-AI-Toolkit592—~4.2kAutomated safety check: PassMIT
Shopify Developmentdavila7/claude-code-templates33k7 repos~2.2kAutomated safety check: PassMIT
Shopify ExpertJeffallan/claude-skills12k—~1.8kAutomated safety check: PassMIT
Shopify Appsdavila7/claude-code-templates33k5 repos~310Automated safety check: PassMIT
Shopify Appssickn33/agentic-awesome-skills47k2 repos~359Automated safety check: PassMIT

Similar skills

  • Shopify

    Shopify/Shopify-AI-Toolkit

    Official

    Build anything on Shopify. An agent skill from Shopify/Shopify-AI-Toolkit.

    592 GitHub stars~4.2k tokensUpdated 3 days ago
    Backend & APIsAuto-check passed

  • Shopify Development

    davila7/claude-code-templates

    Build Shopify apps, extensions, themes using GraphQL Admin API, Shopify CLI, Polaris UI, and Liquid.

    33k GitHub starsUsed in 7 repos~2.2k tokens
    Backend & APIsAuto-check passed

  • Shopify Expert

    Jeffallan/claude-skills

    Builds Shopify themes in Liquid, custom apps, Storefront API storefronts and checkout extensions, using the Shopify CLI to lint, run locally and deploy.

    12k GitHub stars~1.8k tokensUpdated 8 days ago
    Backend & APIsAuto-check passed

  • Shopify Apps

    davila7/claude-code-templates

    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.

    33k GitHub starsUsed in 5 repos~310 tokens
    Backend & APIsAuto-check passed

  • Shopify Apps

    sickn33/agentic-awesome-skills

    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.

    47k GitHub starsUsed in 2 repos~359 tokens
    Backend & APIsAuto-check passed

  • Bankr Shopify

    BankrBot/skills

    Shopify Admin & Storefront GraphQL APIs via curl, with Bankr-native bridges.

    1.2k GitHub stars~5.7k tokensUpdated yesterday
    Backend & APIsAuto-check passed

More from jeremylongshore/tons-of-skills-marketplace

All 3,342 skills in this repo

  • Performing Security Code Review

    jeremylongshore/tons-of-skills-marketplace

    Execute this skill enables AI assistant to conduct a security-focused code review using the security-agent plugin.

    2.8k GitHub starsUsed in 2 repos~1.3k tokens
    Auto-check: notes

  • Adapting Transfer Learning Models

    jeremylongshore/tons-of-skills-marketplace

    Build this skill automates the adaptation of pre-trained machine learning models using transfer learning techniques.

    2.8k GitHub stars~1.1k tokensUpdated today
    Auto-check passed

  • Agent Context Loader

    jeremylongshore/tons-of-skills-marketplace

    Execute proactive auto-loading: automatically detects and loads agents.md files.

    2.8k GitHub stars~1.1k tokensUpdated today
    Auto-check passed

  • Aggregating Performance Metrics

    jeremylongshore/tons-of-skills-marketplace

    Aggregate and centralize performance metrics from applications, systems, databases, caches, and services.

    2.8k GitHub stars~1.2k tokensUpdated today
    Auto-check passed

  • Analyzing Capacity Planning

    jeremylongshore/tons-of-skills-marketplace

    Execute this skill enables AI assistant to analyze capacity requirements and plan for future growth.

    2.8k GitHub stars~947 tokensUpdated today
    Auto-check passed

  • Analyzing Database Indexes

    jeremylongshore/tons-of-skills-marketplace

    Process use when you need to work with database indexing. An agent skill from jeremylongshore/tons-of-skills-marketplace.

    2.8k GitHub stars~2k tokensUpdated today
    Auto-check passed

Works with

Categories

Questions about Shopify Known Pitfalls

What does Shopify Known Pitfalls do?

Identify and avoid Shopify API anti-patterns: ignoring userErrors, wrong API version, REST instead of GraphQL, missing GDPR webhooks, and webhook timeout issues. Shopify Known Pitfalls is an agent skill from jeremylongshore/tons-of-skills-marketplace. Identify and avoid Shopify API anti-patterns: ignoring userErrors, wrong API version, REST instead of GraphQL, missing GDPR webhooks, and webhook timeout issues.

When should I use Shopify Known Pitfalls?

Shopify Known Pitfalls fits situations like: reviewing a Shopify codebase; preparing for App Store submission; debugging mysterious API failures; with phrases like shopify mistakes.

How do I install Shopify Known Pitfalls in Claude Code?

Run `npx skills add jeremylongshore/tons-of-skills-marketplace --skill shopify-known-pitfalls -a claude-code`. Or copy the skill folder (skills/.curated/shopify-known-pitfalls in jeremylongshore/tons-of-skills-marketplace) into .claude/skills/shopify-known-pitfalls in your project. Claude Code loads it when a task matches its description.

How do I install Shopify Known Pitfalls in Codex?

Run `npx skills add jeremylongshore/tons-of-skills-marketplace --skill shopify-known-pitfalls -a codex`. Or copy the skill folder (skills/.curated/shopify-known-pitfalls in jeremylongshore/tons-of-skills-marketplace) into .agents/skills/shopify-known-pitfalls in your project. Codex loads it when a task matches its description.

Can I use Shopify Known Pitfalls in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add jeremylongshore/tons-of-skills-marketplace --skill shopify-known-pitfalls -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/shopify-known-pitfalls, .gemini/skills/shopify-known-pitfalls, .github/skills/shopify-known-pitfalls and .opencode/skills/shopify-known-pitfalls in your project.

What does Shopify Known Pitfalls need to run?

SKILL.md names no scripts, command-line tools or credentials: Shopify Known Pitfalls is instructions for the agent only. Its frontmatter pre-approves these tools: Read, Grep. Compatibility (from SKILL.md): Designed for Claude Code.

Does Shopify Known Pitfalls access the network?

SKILL.md names 1 domain. As links in the text: shopify.dev. This is read from the text; nothing was executed.

Is Shopify Known Pitfalls safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Shopify Known Pitfalls use?

Shopify Known Pitfalls is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Shopify Known Pitfalls use?

About 1.4k tokens (SKILL.md is roughly 5.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 1.8k tokens, read only when the agent opens those files.

What are the alternatives to Shopify Known Pitfalls?

Skills that share tags, products or a category with Shopify Known Pitfalls: Shopify (Shopify/Shopify-AI-Toolkit, 592 stars), Shopify Development (davila7/claude-code-templates, 33k stars), Shopify Expert (Jeffallan/claude-skills, 12k stars) and Shopify Apps (davila7/claude-code-templates, 33k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Shopify Known Pitfalls?

jeremylongshore (a GitHub user) maintains it in jeremylongshore/tons-of-skills-marketplace, which has 2,827 GitHub stars. The repository holds 3,342 skills in this directory. The repository was last updated on October 10, 2026.

Source: jeremylongshore/tons-of-skills-marketplace on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.