saleor-app — Claude Code skill: what it does, how to install
Architectural patterns for building Saleor apps, covering manifest setup, webhooks, payment handling, and Dashboard iframe integration.
npx skills add saleor/agent-skills --skill saleor-app -a claude-codeWhat saleor-app does
This skill guides coding agents through building Saleor integrations via GraphQL and webhooks. While the core communication protocol works with any backend stack, the included patterns rely on Next.js examples built with @saleor/app-sdk.
Instructions are structured across prioritized categories. The skill covers the initial registration handshake, signature verification, and synchronous or asynchronous webhook lifecycles. It also outlines rules for payment processing with the Transaction API, domain-scoped settings persistence via EncryptedMetadataManager, and UI synchronization through AppBridge.
Without verifying user JWT tokens on every route, iframe-embedded apps expose administrative actions. The guide enforces strict scope separation between app-level tokens and dashboard user sessions.
What it helps with
- configure an app manifest with required webhook subscriptions
- verify Saleor webhook signatures and handle asynchronous event retries
- implement payment flows using the Transaction API and provider events
- embed custom interfaces into the Saleor Dashboard with AppBridge
Example prompts for the agent
- Write a Saleor app manifest registering order creation and payment webhooks
- Implement webhook signature verification using
@saleor/app-sdkin Next.js - Set up domain settings storage with
EncryptedMetadataManager
How to install saleor-app
1Skills CLI (Vercel)
npx skills add saleor/agent-skills --skill saleor-app -a claude-code2Manually: put the files in place
~/.claude/skills/saleor-app/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/saleor-app/
1Skills CLI (Vercel)
npx skills add saleor/agent-skills --skill saleor-app -a codex2Manually: put the files in place
.agents/skills/saleor-app/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add saleor/agent-skills --skill saleor-app -a cursor2Manually: put the files in place
.cursor/skills/saleor-app/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install saleor/agent-skills saleor-app2Manually: put the files in place
.github/skills/saleor-app/SKILL.md1Skills CLI (Vercel)
npx skills add saleor/agent-skills --skill saleor-app -a gemini-cli2Platform CLI
gemini skills install https://github.com/saleor/agent-skills --path skills/saleor-appManually: put the files in place
.devin/skills/saleor-app/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add saleor/agent-skills --skill saleor-app -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about saleor-app
How to install saleor-app in Claude Code?
Run npx skills add saleor/agent-skills --skill saleor-app -a claude-code. Claude Code will place the skill file in ~/.claude/skills/saleor-app/SKILL.md.
What does saleor-app cover?
It defines rules for building Saleor apps, including manifest setup, webhook verification, payment transactions, and Dashboard AppBridge integration.
Is the skill restricted to Next.js?
No, the underlying protocol is framework-agnostic, though the specific reference implementations in the guide use Next.js and @saleor/app-sdk.
Source text
SKILL.md · MIT
--- name: saleor-app description: > Universal Saleor app development patterns. Covers the app protocol (manifest, registration, webhooks, authentication), payment processing, SDK abstractions, settings persistence, and Dashboard integration. Framework-agnostic with Next.js examples. license: MIT metadata: author: saleor version: "1.0.0" --- # Saleor App Guide for building apps that extend Saleor via webhooks and the GraphQL API. Framework-agnostic protocol documentation with Next.js examples using `@saleor/app-sdk`. ## When to Apply - Defining an app manifest or registering webhooks - Handling async/sync webhook events from Saleor - Building payment apps with the Transaction API and provider webhooks - Authenticating requests (registration handshake, JWT, signature verification) - Storing app settings in Saleor metadata - Building Dashboard UI inside the iframe - Making GraphQL calls with app tokens - Debugging webhook failures, auth errors, or permission issues - Deciding who can view the app and what they should see (user vs app scope) ## Rule Categories by Priority | Priority | Category | Impact | Prefix | | -------- | --------------- | -------- | --------------- | | 1 | Protocol | CRITICAL | `protocol-` | | 2 | Permissions | CRITICAL | `permissions-` | | 3 | Payment Apps | CRITICAL | `payment-` | | 4 | Webhooks | HIGH | `webhook-` | | 5 | Data & Settings | HIGH | `data-` | | 6 | Dashboard UI | MEDIUM | `dashboard-` | | 7 | Development | MEDIUM | `dev-` | ## Quick Reference ### 1. Protocol (CRITICAL) - `protocol-manifest` — App manifest, required endpoints, permissions, extensions - `protocol-auth` — Registration handshake, APL, token scopes, JWT/signature verification ### 2. Permissions (CRITICAL) - `permissions-access-scopes` — Define per-feature permissions; guard user JWT on every API route; baseline + per-route meta; UI mirrors server ### 3. Payment Apps (CRITICAL) - `payment-app` — Financial truth, stable references, unknown outcomes, refunds, and reconciliation ### 4. Webhooks (HIGH) - `webhook-async` — Async event handling, payload typing, retry policy, signature verification - `webhook-sync` — Sync event handling, response schemas, performance constraints - `webhook-external` — Receiving webhooks from external services, multi-tenant routing ### 5. Data & Settings (HIGH) - `data-graphql` — GraphQL from apps: client setup, auth headers, codegen, app vs user tokens - `data-settings` — MetadataManager, EncryptedMetadataManager, domain-scoped persistence ### 6. Dashboard UI (MEDIUM) - `dashboard-appbridge` — AppBridge iframe protocol, actions, events, theme/locale sync ### 7. Development (MEDIUM) - `dev-debug` — Common errors, webhook dry runs, tunnel setup, debugging checklist
© saleor · MIT · saleor/agent-skills
