Przejdź do treści
Biblioteka skilli
Sprzedaż i obsługa klienta · Planowanie

shop-plan

/shop-plan

Dobiera ścieżkę budowy sklepu Xsolla: bez interfejsu lub Shop Builder, a przy Shop Builderze także rodzaj strony, i zapisuje decyzję.

Repozytorium
xsolla-ai-kit ↗
Licencja
MIT
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

87/ 100Klasa: dobry
Format20 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność17 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
3
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Dobiera ścieżkę budowy sklepu Xsolla: bez interfejsu lub Shop Builder, a przy Shop Builderze także rodzaj strony, i zapisuje decyzję.

Wyzwalacze z opisu

plan my shopwhich Xsolla path should I useheadless or Shop Buildershould I use Shop Builder or build my ownwhat
Oryginalny opis (EN)

Resolves the build path — headless or Shop Builder — and, on Shop Builder, whether the site is a shop or a Game Web Portal, before any Xsolla shop gets built. Walks through five criteria for the path (custom UI needs, hosting, time to launch, dev capacity, localization/theming) and a sixth for the site kind (does the game need a home around the store), shows the trade-offs to the developer, and records the confirmed choice. Use for "plan my shop", "which Xsolla path should I use", "headless or Shop Builder", "should I use Shop Builder or build my own", "what's fastest to launch a store", "I wa

Jak działa

  1. When to use
  2. Prerequisites
  3. Happy path
  4. What actually differs
  5. Steps
  6. Common pitfalls
  7. Known limitations
  8. Agent test
Sekcje z nagłówków SKILL.md, w oryginale · 227 linii, 1 938 słów
Podgląd SKILL.md
---
name: shop-plan
description: >-
  Resolves the build path — headless or Shop Builder — and, on Shop Builder, whether the site is a
  shop or a Game Web Portal, before any Xsolla shop gets built. Walks through five criteria for
  the path (custom UI needs, hosting, time to launch, dev capacity, localization/theming) and a
  sixth for the site kind (does the game need a home around the store), shows the trade-offs to
  the developer, and records the confirmed choice. Use for "plan my shop", "which Xsolla path
  should I use", "headless or Shop Builder", "should I use Shop Builder or build my own", "what's
  fastest to launch a store", "I want a hosted no-code store", "I want to embed a custom store in
  my app", "compare headless vs Shop Builder", "help me decide between headless and Shop Builder",
  "do I need a Game Web Portal or just a shop", "gather requirements for my shop", or any request
  to decide the build path before building. Runs with zero Xsolla credentials — `shop-setup`
  invokes this automatically when no path is recorded in `.env`. Creates no Xsolla resources and
  writes nothing until the developer explicitly confirms the recommendation.
metadata:
  owner: s.sadruddin
  domain: orchestrator
  status: draft
---

# Xsolla shop planning — headless or Shop Builder, shop or portal

Resolve the one decision that shapes everything downstream, **before** the developer has an
Xsolla account, a project, or any credentials. `shop-setup` (the build orchestrator) invokes this
automatically when it finds no recorded path — this skill is the only asker.

## When to use

Use when the developer wants to **decide which path to build on**, or asks a want/tradeoff
question that sounds like a build request but is really a planning one — "I want a hosted
no-code store" and "embed a custom store in my app" are both planning requests, not build
requests, until a path is recorded.

**Do not use this to build anything.** This skill creates no Xsolla account, project, or
resource, calls no Xsolla API, and runs no `xsolla` command — not even `--version`; checking the
CLI belongs to `merchant-setup`. If a path is already recorded in `.env` and the developer
hasn't asked to reconsider it, report it in one line and stop — don't re-interview.

## Prerequisites

**None.** No Xsolla account, project, or API key is needed — that is the point of deciding
before building.

## Happy path

"I'm a solo indie dev, no website, need a store live this week" → no path in `.env`, so ask the six
criteria in one message → show the comparison, recommend Shop Builder and name the criteria that
drove it → developer says yes → `XSOLLA_BUILD_PATH=shopbuilder` and `XSOLLA_SITE_KIND=shop`
recorded → stop.

## What actually differs

| | **Headless** | **Shop Builder: shop** | **Shop Builder: Game Web Portal** |
|---|---|---|---|
| What it is | A store in the developer's own site/app | A hosted store | A hosted game home — Home, News, Rewards, Community, optional Launcher — around a Web Shop |
| Who writes the UI | The developer, in their own site/app | Nobody — Xsolla-hosted, no-code | Nobody — Xsolla-hosted, no-code |
| Where it lives | The developer's own domain | An Xsolla-hosted domain | An Xsolla-hosted domain |
| Payment layer | Headless Checkout SDK, embedded | Xsolla Pay Station, hosted | Xsolla Pay Station, hosted |
| Time to a live store | Longer — it's a frontend build | Short | Short for the store; the sections need content |
| Ceiling on custom design | None | Bounded by the block system | Bounded by the block system |
| Ongoing maintenance | The developer's own frontend | None — Xsolla maintains the UI | None for the UI; the news and rewards content is the developer's |

**Whichever path, recording the choice is where this skill stops — `shop-setup` does the building.**
Headless runs `shop-setup` → `catalog-design`, `login-setup`, `headless-checkout-integration`,
`webhooks-impl`, `production`. Shop Builder runs the same shared foundation, then hands the
storefront to `description-to-shop` or `shop-builder-assembly`, and finishes with `webhooks-impl`.
For a Game Web Portal, those two hand the storefront on to `game-web-portal`.

## Steps

### 1. Check for an existing decision

```bash
raw=$(grep -E '^XSOLLA_BUILD_PATH=' .env 2>/dev/null | tail -n 1 | cut -d= -f2-)
case "$raw" in
  "")                   echo NO_DECISION ;;
  headless|shopbuilder) echo "DECIDED:$raw" ;;
  *)                    echo "INVALID:$raw" ;;
esac
```

**`DECIDED`** — on `shopbuilder`, also read the site kind with the
[contract's check](references/build-path-contract.md#the-site-kind-shop-builder-only); an invalid
kind is handled like an invalid path, below. Unless the developer explicitly asked to reconsider
("replan", "reconsider", "change the path"), report the decision and stop:

```
Already decided: Shop Builder, a Game Web Portal.
Say "reconsider" to redo it, or run shop-setup to build.
```

**`INVALID`** — `.env` holds a value that isn't one of the two (a hand-edit, a typo, a stray
quote). **Do not treat this as undecided and start interviewing.** Somebody made a decision
here; silently re-asking throws it away. Show the value and ask which they meant:

```
.env has XSOLLA_BUILD_PATH=Headless, which isn't a value I recognize — it must be exactly
`headless` or `shopbuilder`. Did you mean headless? I'll correct it if you confirm.
```

**`NO_DECISION`** — nothing recorded (or no `.env` at all). Continue to step 2.

Full rules, including what every other skill must do with this key:
[`references/build-path-contract.md`](references/build-path-contract.md).

**Credentials are not a decision.** A project with `XSOLLA_PROJECT_ID` / `XSOLLA_PROJECT_API_KEY`
in `.env` but no recorded path has an Xsolla project, not a chosen storefront — every path builds on
the same account and catalog. Ask the six criteria as normal. Say what you can see, so the
developer knows the account work isn't being redone:

```
You already have an Xsolla project configured — that part carries over whichever path you pick.
What's still open is how the storefront itself gets built, so six quick questions.
```

### 2. Ask the six criteria — one message

Ask all six in a single message. Unless the request is plainly headless, the same message also
asks the rest of the [intake](references/onboarding-contract.md#intake) — the game and site
details the Shop Builder part needs — so the developer answers one round of questions, not two.
Infer an answer only when the request already states it plainly (e.g. "embed this in my existing
React app" answers custom UI *and* hosting) — but still show your inference back before moving
on, so a wrong read gets caught immediately.

1. **Custom UI needs.** Do you already have a frontend/site this plugs into, or do you want one
   built for you?
2. **Hosting.** Does the store need to live on your own domain, or is an Xsolla-hosted domain
   fine?
3. **Time to launch.** How soon do you need this live — days, or is a longer build okay?
4. **Dev capacity.** How much developer time can you put into building and maintaining a custom
   storefront — none, a little, or a lot? *(Ask this directly — don't infer it from phrasing like
   "don't want to write a frontend," which is a preference, not a capacity answer.)*
5. **Localization / theming.** Do you need more than one language or region, or custom visual
   theming beyond picking a color and a logo?
6. **Game home.** Does the game need a home around the store — news, rewards, community, a
   launcher — or only a store?

### 3. Weigh and recommend — show the trade-offs, name the drivers

Never silently pick a side and never shortcut to "one question, two options." Show the
comparison table from "What actually differs" above (or a condensed version of it) **to the
developer**, then state the recommendation and **which of the criteria drove it**. The first five
decide headless or Shop Builder. On Shop Builder, criterion 6 decides the site kind: a game home
around the store means a Game Web Portal, only a store means a shop. On headless it doesn't apply —
the developer builds their own site:

```
Recommending Shop Builder: you have no existing frontend, want it live this week, and have
little dev time to spend on a custom storefront — hosting and custom UI weren't blockers for
you, and you only need a store. Trade-off: you lose the design ceiling headless gives you.

| ... trade-off table ... |

Go with this, or would you rather build headless?
```

On Shop Builder, the same message lists the intake values that will be recorded, so the
developer's yes covers them too.

If the answers genuinely pull in different directions (e.g. wants full custom UI *and* has
zero dev capacity *and* needs it live tomorrow) — don't average them into a guess. Say plainly
which criteria conflict and ask the developer to break the tie themselves.

### 4. Wait for explicit confirmation — write nothing before it

**Nothing is written — no `.env`, no other local file — until the developer has seen the
trade-offs and the recommendation, and has said yes.** Silence, a topic change, or moving on to
another question is not confirmation. Neither is a "yes" that arrives before the comparison and
recommendation were shown: show them first, then ask again. If they push back or ask a follow-up,
answer it and ask again; don't write on a guess that they've come around.

### 5. Record the choice, then stop

Only after explicit confirmation:

```bash
# Replace in place if the key is already there, append if not. Use if/else, not a
# `grep && sed || echo` chain: when grep matches but sed fails, the `||` still fires
# and you get the key twice.
build_path=shopbuilder   # or headless
if grep -q '^XSOLLA_BUILD_PATH=' .env 2>/dev/null; then
  sed -i.bak "s|^XSOLLA_BUILD_PATH=.*|XSOLLA_BUILD_PATH=$build_path|" .env && rm -f .env.bak
else
  echo "XSOLLA_BUILD_PATH=$build_path" >> .env
fi
grep -q '^\.env' .gitignore 2>/dev/null || echo '.env' >> .gitignore
if [ "$build_path" = shopbuilder ]; then
  site_kind=portal   # shop or portal
  if grep -q '^XSOLLA_SITE_KIND=' .env; then
    sed -i.bak "s|^XSOLLA_SITE_KIND=.*|XSOLLA_SITE_KIND=$site_kind|" .env && rm -f .env.bak
  else
    echo "XSOLLA_SITE_KIND=$site_kind" >> .env
  fi
  mkdir -p .xsolla
  grep -qxF '.xsolla/' .gitignore 2>/dev/null || echo '.xsolla/' >> .gitignore
fi
```

On headless, record the path only. On Shop Builder, at the same confirmation, write
`.xsolla/onboarding.json` with the intake, the path and the site kind, as
[the onboarding contract](references/onboarding-contract.md#the-ledger) describes. When the
developer reconsiders, update the ledger's path, site kind and intake in the same step. On a
switch to headless, delete the ledger and remove `XSOLLA_SITE_KIND` from `.env`. Report what was
recorded and stop — do not chain into `shop-setup` or any build step:

```
Recorded: Shop Builder, a Game Web Portal. Run shop-setup when you're ready to build.
```

## Common pitfalls

- **Asking one question with two options instead of showing the comparison.** The developer
  needs the trade-offs in front of them, not a bare fork.
- **Inferring dev capacity or localization needs from unrelated phrasing.** Ask them directly —
  "don't want to write a frontend" is about preference, not capacity.
- **Writing `.env` before an explicit yes.** A shown recommendation is not a confirmed one.
- **Re-interviewing when `.env` already has a recorded path.** Check first, every time.
- **Averaging conflicting answers into a guess.** Name the conflict and ask, rather than picking
  the side with more signals.
- **Reading existing credentials as a path.** An account and a catalog are shared by every path;
  only `XSOLLA_BUILD_PATH` and `XSOLLA_SITE_KIND` record a decision.
- **Recording a site kind on the headless path.** It applies to Shop Builder sites only.

## Known limitations

- **Only the path, the site kind and the Shop Builder intake are planned.** The catalog is not
  gathered here yet.
- **Only `shop-setup` checks the recorded path, and only the Shop Builder skills read the site
  kind.** No other skill reads them, so invoking one directly (e.g. `headless-checkout-integration`
  on a `shopbuilder` project) isn't stopped.
- **The step 1 and step 5 snippets are compound shell commands**, so Claude Code may ask the
  developer to approve them.

## Agent test

Prompt: "I'm a solo indie developer and I want to sell a few skins and a currency pack for my
game. I have no website and no frontend skills or time to build one. An Xsolla-hosted domain is
totally fine. I need it live this week. English only, and just my logo and brand colors are enough."

Result: `shop-plan` selected, the comparison shown, Shop Builder recommended with the criteria that
drove it named, nothing written until "yes", then `shopbuilder` and the site kind `shop` recorded
once and the agent stopped. Across 22 fixed intents, two rounds each (2026-10-06, including two
portal intents and a store that is not a portal): the recommended path and site kind matched the
known answer 27/27, zero writes or `xsolla` calls before confirmation across 35 runs, and headless
prompts still reached their own skills 10/10. ✅
Pliki w paczce (3)
  • SKILL.md 13 KB
  • references/build-path-contract.md 5 KB
  • references/onboarding-contract.md 10 KB

Wersje

W bazie nie ma innych skilli o nazwie shop-plan.

Identyczna treść występuje jeszcze w 1 innych folderach na GitHubie. Tu pokazujemy jedną, najlepiej ocenioną kopię.

Migawka bazy z 13.11.2026 · wersja paczki 2571c001d684 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100nocode-shop-setup
    Buduje sklep internetowy dla gry w Shop Builder Xsolla bez kodu i wdrożeń, instaluje CLI Xsolla, a logowanie wykonuje użytkownik.
  • 90shop-builder-assembly
    Składa sklep Xsolla Shop Builder z gotowego opisu: motyw, strony, nawigację, bloki, lokalizację i powiązania z katalogiem.
  • 100tiktok-shop-brain
    Odpowiada na pytania sprzedawców TikTok Shop o GMV, dobór twórców, prowizje, reklamy i mechanizmy platformy, bez danych na żywo.
  • 100tiktok-shop-webhooks
    Odbiera i weryfikuje webhooki TikTok Shop, w tym podpis w nagłówku Authorization oraz zdarzenia ORDER_STATUS_CHANGE, PACKAGE_UPDATE, PRODUCT_STATUS_CHANGE i SELLER_DEAUTHORIZATION.
  • 100shop-app-research
    Wyszukuje produkty, warianty i sklepy w Shop.app przez API Crawlora i zwraca czysty JSON, zamiast scrapować strony.
  • 100np-shop-offer-fit
    Dopasowuje ofertę małego sklepu technologicznego do potrzeby kupującego, by była trafna i możliwa do obsłużenia.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.