catalog-design
Skill9 starsChanged 5 months agoMITView on GitHub
Sets up an Xsolla catalog: virtual items, virtual currency and its packages, bundles, game keys, item groups, regional prices and LiveOps offers, plus the client purchase flow (buy by SKU or cart, buy for virtual currency, order status). Use for "set up my Xsolla catalog", "create virtual items", "sell game keys", "regional prices".
- Reads credentials
In this repository33 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/xsolla-ai-kit.mdcCursor rule
- description-to-shopSkill
- game-web-portalSkill
- headless-checkout-integrationSkill
- login-setupSkill
- login-stylingSkill
- merchant-setupSkill
- nocode-shop-setupSkill
- productionSkill
- quest-setupSkill
- shop-builder-assemblySkill
- shopbuilder-translateSkill
- shop-setupSkill
- webhooks-implSkill
- xla-pagesSkill
- catalog-designSkill
- description-to-shopSkill
- game-web-portalSkill
- headless-checkout-integrationSkill
- login-setupSkill
- login-stylingSkill
- merchant-setupSkill
- nocode-shop-setupSkill
- productionSkill
- quest-setupSkill
- shop-builder-assemblySkill
- shopbuilder-translateSkill
- shop-setupSkill
- webhooks-implSkill
- xla-pagesSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 4 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 28
Use this skill when the developer wants to:
- Distinctive: line 30
Create virtual items, virtual currency, VC packages, bundles, or item groups
- Distinctive: line 33
Add limited-time offers, purchase limits, promotions, offer chains, daily rewards or a reward system — "limited-time offer", "purchase …
- Very specific: line 66
Choose the archetype and set up the catalog (Admin API): Ask which of the two the game needs (or both): in-game items (typical mobile/F2P) …
- Very specific: line 96
Implement purchase: Default to fast purchase by SKU: client-side Create order with specified item (user JWT) → returns order_id + payment …
- Very specific: line 122
A permanent unlock sold as a consumable: Check what each product means, not only its name and price.
- Distinctive: line 135
Game keys + Pay Station Embed/iframe: Not supported — sell keys via a new window or direct link.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Status
This skill is a draft authored by the catalog SME (@p.sanachev, Tech Lead, IGS-Left).
Detailed material lives in references/:
references/items.md— virtual items, VC, packages, bundles, groups (Admin API)references/game-keys.md— key packages, platforms, entitlementreferences/pricing.md— local prices, regional restrictionsreferences/liveops.md— limits, time-limited offers, promotions, chains, reward systemreferences/catalog-client.md— client catalog callsreferences/purchase-and-tracking.md— purchase flows, order confirmation
When to use
Use this skill when the developer wants to:
- Create virtual items, virtual currency, VC packages, bundles, or item groups
- Sell a game or DLC via game keys (Steam, Epic, PlayStation, DRM-free, …)
- Set local prices per country or restrict sales by region
- Add limited-time offers, purchase limits, promotions, offer chains, daily rewards or a reward system — "limited-time offer", "purchase limit", "first purchase bonus", "offer chain", "daily rewards", "reward system", "promo codes"
- Build the store catalog UI on the client (game or website)
- Implement purchase: fast purchase by SKU, cart, purchase for VC, free items
- Confirm purchases: webhooks on the server or order tracking on the client
Out of scope: player inventory, server-side cart, refund handling, payment UI
configuration (→ headless-checkout-integration), webhook handler code (→ webhooks-impl).
Prerequisites
export XSOLLA_MERCHANT_ID=<your merchant ID>
export XSOLLA_PROJECT_ID=<your project ID>
export XSOLLA_PROJECT_API_KEY=<your API key>- An Xsolla project (run
merchant-setupfirst — it sets up these variables). - Check what the project already has. A new project can come with a demo catalog: a
virtual currency, packs, items, a bundle and groups whose SKUs or IDs start with
demo. List the catalog first; if demo entries exist, ask whether to keep, hide or replace them before adding anything. - Xsolla MCP (strongly recommended). Connect the official Xsolla MCP server
(https://developers.xsolla.com/get-started/ai-assistants/). Before calling any
Admin API, verify the current request schema with the
search_xsolla_sourcestool — this skill links the right operations, but field-level schemas must come from live docs, not from this file. If the MCP is unavailable, fetch the linked developers.xsolla.com pages, and say in your reply that the schemas came from the docs pages, not the MCP.
Steps
- Choose the archetype and set up the catalog (Admin API). Ask which of the two
the game needs (or both): in-game items (typical mobile/F2P) — groups → virtual
currency → virtual items → VC packages → bundles, see
references/items.md; or game sales via keys — a key package per platform → upload keys, seereferences/game-keys.md. Admin calls use basic auth (XSOLLA_MERCHANT_ID:XSOLLA_PROJECT_API_KEY); verify each request body via the Xsolla MCP first. - Propose a complete shop, not a price list. For in-game items, propose by default
what gives players reasons to buy and to return: bundles and a starter pack, a
first-purchase bonus, time-limited offers, per-player limits, an offer chain, daily
rewards, a reward system and promo codes — a coherent set for the
game, not all of them. Explain each in plain words and ask for every missing
commercial value in one message; create nothing before the developer's yes. See
references/liveops.md. On the Shop Builder path,nocode-shop-setupasks those values in its one batch and shows the proposal with the site plan, so a single yes covers both; don't ask for a separate one. - Set up pricing. Recommend regional prices in local currencies for key markets
via the
pricesarray; keep the currency list and default currency identical across all items. For game keys, optionally add regional sale restrictions (regions →regionsarray) — depends on the game. Seereferences/pricing.md. - Build the catalog on the client (Catalog API). Render the store from
client-side Catalog calls for the specific item types you sell (
Get virtual items list,Get virtual currency list,Get list of bundles,Get games list), called from the client without acountryparameter — country, prices, and regional availability resolve from the user's IP. Never use Admin calls for the storefront. Seereferences/catalog-client.md. - Implement purchase. Default to fast purchase by SKU: client-side
Create order with specified item(user JWT) → returnsorder_id+ payment token → open Pay Station with the token. Cart, purchase for VC, free items, and game-key specifics:references/purchase-and-tracking.md. The payment step itself belongs to theheadless-checkout-integrationskill. - Confirm the purchase. Server (recommended): handle
order_paid/order_canceledwebhooks — implement with thewebhooks-implskill. Client (no server): WebSocket order status + short-pollingGet orderfallback. Seereferences/purchase-and-tracking.md. - Verify end-to-end. In sandbox (
"sandbox": true, test cards): fetch the catalog via a Catalog call, buy an item, confirm the order reachesdone, and the confirmation path (webhook or socket) fired.
Common pitfalls
- Order creation from the server. Client payment calls resolve country → currency →
payment methods from the caller's IP. Call them from the client; don't pass
currency/country. (Server-side token generation is a separate API that requirescountry.valueorX-User-Ip— preferX-User-Ipfor greenfield shops; seepayment-country.) - Admin API on the storefront. Admin calls are rate-limited and not for user traffic; catalogs are built from Catalog-subsection calls, per item type.
- Update wipes fields. Admin update calls replace, not merge: GET the item first
and send back everything you want to keep (e.g. omit
limits→ limits deleted). - A permanent unlock sold as a consumable. Check what each product means, not only its
name and price. A one-time unlock such as No Ads is
non_consumable, the docs' own example, withlimits.per_usertotal 1 so it can't be bought twice. - Inconsistent currencies break the catalog. Different currency sets or default
currencies across items cause fallback prices or
price: nullon the storefront. - Bundles missing from a read-back. Listing a group's items doesn't return its
bundles: read bundles back with the bundle list (
Get list of bundles, or the CLI's bundles-by-group command) before deciding one is missing or hidden. - Products without pictures. Give every item, pack and bundle its own image, from the game's art the developer approved. List the products still without one in the handoff.
- Wrong webhook set. Accounts registered after 2025-01-22 get combined
order_paid/order_canceled; older accounts also receive separatepayment/refundand must process them all. - Game keys + Pay Station Embed/iframe. Not supported — sell keys via a new window or direct link. With reglocks assigned, keys upload only via the Upload codes API.
Agent test
Prompt: "Configure my Xsolla catalog with items and pricing, then wire up purchase and order confirmation. It's a mobile F2P game with gems (virtual currency), gem packs, boosters, and a starter bundle."
Live run on sandbox project 173042 (2026-06-11): the agent discovered and applied
this skill (+ webhooks-impl for confirmation context), verified schemas via the Xsolla
MCP as mandated, and executed the real flow — created 3 groups, virtual currency, a
consumable booster priced in VC, 2 VC packages, and a per-user-limited starter bundle
(all 201); read everything back via typed client Catalog calls without country
(IP-resolved USD prices, 200); created a server-side sandbox order + payment token
(201, not paid); then deleted every created entity (204, verified empty). Steps
requiring a user JWT (fast purchase, VC purchase, Get order/WebSocket) were planned and
documented as blocked: no Login on the fixture project. ✅
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

