feat: add game-web-portal skill

[apyanzin-xsolla]

Agentic onboarding for a PC/Steam Game Web Portal: the agent creates or resumes a verified portal and returns an evidence-backed partner handoff. Supersedes #25 — same skill, with the delegation blocker fixed.

skills/game-web-portal/SKILL.md                          150 lines
skills/game-web-portal/references/agentic-onboarding.md  187 lines
skills/game-web-portal/references/portal-api.md          293 lines

Plus the registry rows: skills/README.md, and the AGENTS.md inventory table + trigger block (mirrored into its byte-identical CLAUDE.md).

What changed since #25

@JavadManashti's blocker was that Step 4 routed pages, blocks, theme, localization and preview to shop-setup, which has no Shop Builder coverage — so the portal work dead-ended. Option (1): the skill is now self-sufficient.

references/portal-api.md documents the Shop Builder API the portal steps actually call — endpoints per stage, the domain vs landing _id split, the batch-patch and localization payload shapes, known API issues, and a response → status mapping. Delegation is kept only for the surrounding products: merchant-setup, catalog-design, login-setup, headless-checkout-integration.

Three findings worth a maintainer's eye:

• Publication is per-page. POST .../landing/{domain}/publication takes a page selection — draftPagesIds — and the main page must be live or in the same selection; child pages cannot be published before it. This is why verify-website returns 400: the CLI omits the selection. The exact field shape is marked unverified in the reference pending a live call.
• The preview 403 comes from the CLI reading public-preview/public-preview-last-token, which is not part of the published API. public-preview-link is.
• Auth is not the project API key. Portal operations authenticate with a Publisher Account admin token (the CLI wraps the same service with a pa-v4-token session cookie), so the skill treats 401/403 as needs_access rather than a capability block. Worth deciding whether the kit wants a shared convention here.

There is no Community page template, so that section returns needs_input rather than guessing a layout. Launcher builds, installers and downloads are not exposed by this API and stay blocked_capability.

Review items from #25

• Registry rows — included here, not a follow-up.
• status: draft — added.
• Owner — a.pyanzin, per repo convention rather than the guide's GitHub-handle format.
• domain: orchestrator — unchanged; the shop-setup routing line is yours to add as you described.

Agent test

Prompt: Use Xsolla CLI to set up my PC Game Portal. plus a Steam store URL, merchant ID, project ID, domain, and primary locale.

Result: 12/12 hard-case runs passed with the skill loaded, versus 6/12 with no context. Judge confidence 100%, first-try success 100%, pass@3 100%, zero safety errors. Mean token usage 1.41× the official-docs baseline against a ≤1.5× target. 36 runs across four hard PC onboarding scenarios, three variants, three repetitions.

Source, including the specification and the eval harness: https://github.com/apyanzin-xsolla/game-web-portal

[apyanzin-xsolla]

@JavadManashti went with option (1) — the skill no longer depends on shop-setup for the portal work. references/portal-api.md carries the Shop Builder API surface, and delegation is now only for merchant, catalog, Login and checkout.

Two things that came out of writing it and are really platform questions, not skill ones: publication turns out to be a per-page selection (that's the draftPagesIds 400 — the call omits the selection), and the preview 403 is the CLI reading public-preview-last-token, which isn't part of the published API. Details in the PR description.

Registry rows, status: draft and the owner format are all in here. #25 is superseded — happy to close it once you've had a look.

[JavadManashti]

Ran this through the new skill validator (landing in #28) against this branch: only 1 finding, and it's a mechanical one.

Blocking: .cursor/skills/game-web-portal/** mirror is missing. It's generated from skills/game-web-portal/** (see sync-providers.yml / CONTRIBUTING.md) — running:

rm -rf .cursor/skills && mkdir -p .cursor/skills
for d in skills/*/; do [ -f "$d/SKILL.md" ] && cp -R "$d" ".cursor/skills/$(basename "$d")"; done
cp AGENTS.md CLAUDE.md

and committing the result should be all that's needed (CLAUDE.md is already in sync, so that step is a no-op here).

Confirmed fixed from #25: registry rows are in both skills/README.md and AGENTS.md, status: draft is set, and the delegation blocker is resolved — portal-api.md now documents the Shop Builder endpoints directly instead of routing to shop-setup coverage that didn't exist. Good writeup on the three open API questions (per-page publication payload, the preview-token 403, and PA-token auth) — agreed those are worth a maintainer decision rather than guessing.

Non-blocking: owner is written as @a.pyanzin (LDAP-style); repo convention per CODEOWNERS is GitHub handles — @apyanzin-xsolla here. Not a merge blocker, just flagging for consistency with the other skills.

Nice fix on the actual blocker — this is mergeable once the .cursor/skills mirror is committed.

[apyanzin-xsolla]

@JavadManashti mirror is in — .cursor/skills/game-web-portal/** committed in 13e2d80, generated with the steps from sync-providers.yml. CLAUDE.md was already in sync, so that step was a no-op as you expected. Nothing else touched. Ready for your review whenever you have a moment.

One heads-up on that snippet: cp -R copies whole skill directories, so on a dirty working tree it also pulls in untracked subdirectories — I had local evals/ folders in six skills that landed in the mirror and had to be removed before committing. Might be worth switching the workflow to a git archive-based copy, or excluding non-tracked paths, so nobody accidentally commits stray files into .cursor/skills.

[JavadManashti]

Thanks for adding the .cursor/skills mirror — that clears the one blocker I had.

Re-ran the validator (now live on main as of #28) against this branch. One error left, and it's my fault rather than yours:

skills/game-web-portal/SKILL.md: metadata owner 'a.pyanzin' is not in the known-owners list

#28 added an allowlist for metadata.owner and landed after you opened this, so your legitimate owner id reads as a typo. #31 registers a.pyanzin and a.springut — once that merges, this branch validates clean with no change needed from you. Nothing to do on your side; just noting why CI will be red until then.

Everything else passes: frontmatter, description length, both registries, generated-file sync, links, and the 500-line target (your SKILL.md is well under).

The three API findings in your description — per-page publication payload, the public-preview-last-token 403, and PA-token auth — are the parts I'd still like a second opinion on before this goes in, since they're marked unverified. @e.chernykh or @y-klochikhin, either of you able to sanity-check those three against the actual Shop Builder behaviour?

[JavadManashti]

Following @y-klochikhin's review — I want to separate the two things in it, because one is a product decision and the other is a mechanical bug we can fix in this PR today.

The routing concern is real, and it's narrower than it looks

I checked it against the branch rather than reasoning about it. Three skills would carry domain: orchestrator — merchant-setup, shop-setup, game-web-portal — so this isn't "a second orchestrator" so much as a third. That part is fine on its own.

The actual defect is where the disambiguation lives. game-web-portal/SKILL.md:37 says exactly the right thing:

Use shop-setup instead for a general zero-to-shop storefront; this skill is the PC/Steam portal path

But that's in the body, and routing happens off the description. By the time an agent reads line 37 it has already chosen this skill — the handoff never fires. Meanwhile shop-setup, which is the declared "START HERE" entry point, contains zero occurrences of the word "portal", so it has no way to route the other direction either.

Concrete collision — "build a web shop for my PC game":

	matches on
shop-setup	"START HERE for any request to build a shop", "build me a shop", "game shop"
game-web-portal	"PC", "Web Shop", "wiring a Web Shop … into a portal"

Both match strongly, and nothing in either description breaks the tie. That's the ambiguity Yaroslav is pointing at, and it's demonstrable rather than theoretical.

The fix is two sentences, not an architecture change. One disambiguating clause in each description:

• game-web-portal — something like: "For a coded storefront built on Store API + Headless Checkout, use shop-setup instead; this skill is the no-code PC/Steam portal path."
• shop-setup — the mirror: "For a hosted no-code Game Web Portal (PC/Steam), use game-web-portal instead."

That's the cheapest thing that makes the choice deterministic, and it's worth doing regardless of how the bigger question lands. Happy to push it if you'd like, @apyanzin-xsolla.

The product question isn't mine or this PR's to settle

Whether Site Builder belongs in a kit whose core is Commerce API + Headless Checkout — and whether it competes with shop-setup — is a positioning call for @aaron_springut, as Yaroslav said. I don't think a PR review can resolve it, and I'd rather not have it resolved implicitly by a merge.

I'd note the two of you may be describing different things: Yaroslav is reading this as Site Builder API integration, and @apyanzin-xsolla's reply frames it as agentic onboarding guidance for a Game Web Portal — where a web shop is one tab among News, Community, Login, Pay Station. Those imply different answers, so it's worth settling which one this actually is before debating whether it fits.

Separately: the three API questions

Yaroslav's point stands — these are Site Builder product questions, portal-api.md already marks draftPagesIds as unverified, and they should be closed by a live call or the backend owner, not a kit review. That's a real blocker on merging as-is, independent of everything above.

Status

CI is red here only because of the VALID_OWNERS allowlist I added in #28, which landed after this PR opened. #31 fixes that — nothing for you to do.