agentleFS
xsollaxsolla/xsolla-ai-kit/skills/xla-pages/SKILL.md

xla-pages

Skill9 starsChanged 5 months agoMITView on GitHub

Creates and updates XLA Pages on x.la in Shop Builder: game pages, payment provider pages and combined pages, from @xla-pages blocks bound to the XLA Pages API. Use for "create pages for x.la", "generate XLA game pages", "add a Klarna payment page on x.la", "update the PayPal page on x.la" or an XLA Pages batch file. Never publishes. For any other Shop Builder site, use nocode-shop-setup.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 3 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Add .xsolla/ to the project's .gitignore before the first file goes there.

    line 38
  2. Very specific:

    All scripts are in scripts/ and run with python3 -I.

    line 58
  3. Very specific:

    Preflight: Run preflight_report.py next --pub-dir <run>/pub.

    line 61
  4. Distinctive:

    every page that appears or changes: create, update or unchanged, its route and type, its blocks with versions in order, its bindings, the …

    line 75
  5. Very specific:

    Ask for one explicit yes. A request to "create the pages" is not that yes.

    line 84
  6. Very specific:

    Never publish, enable a preview, run verify-website, or apply or restore a site version.

    line 117
  7. Very specific:

    Never write to the catalog, LiveOps or the XLA Pages API.

    line 118
  8. Distinctive:

    Never add a standard Shop Builder block, a Custom Block, a Custom code block, a block script, styles, fonts, iframes or trackers.

    line 119
  9. Very specific:

    Never pass --force; never call a command outside scripts/xla_common.py's list.

    line 121
  10. Distinctive:

    Never write to a site other than the configured one, or to a copy of it.

    line 122
  11. Very specific:

    Never commit .xsolla/, a plan, a backup or saved responses: they hold real IDs.

    line 123

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

XLA Pages

Build and update XLA Pages on x.la in Shop Builder. The manifest is the spec: page types, blocks, bindings, writes and checks. Anything it doesn't list is not allowed. The general Shop Builder rules (standard blocks first, Custom Blocks where needed, theme and copy from a brief) don't apply to these pages.

The scripts do the checking; follow their output and never work around a refusal. Data connections, bindings and SEO go through commands the CLI has today (update-block, update-many-localization), stored the way Site Builder stores them. Today's CLI can't create a dynamic page or add a block at a pinned version, so a batch that creates a page stops at the gate with zero writes; an update of an existing page runs. Show the user the gate's report: it names the missing commands and flags, which the Shop Builder team tracks.

Before anything

  • The site. One Shop Builder site, written in its draft only. Its merchant, project and slug live in the user's .xsolla/xla-pages.json, never in this repository (it's public):

    {"merchant_id": 0, "project_id": 0, "site_slug": "<slug>", "write_to_published_site": true}

    Add .xsolla/ to the project's .gitignore before the first file goes there. The site is live: write_to_published_site: true is the one exception to "never write to a published site", and only for that configured site. Ask the user for these values if the file is missing.

  • Updates of existing pages are off until one run on a single test page confirms their write shapes (the manifest's writes.updates). For that run only, the user adds "allow_unverified_updates": true to the local config; the plan may then update one page and create none. A person checks the page in the Editor, then verified: true goes into the manifest through a pull request and the flag comes out of the local config.
  • The CLI. Signed in (xsolla auth login, in the user's own terminal) and pointing at that merchant and project with sandbox mode off (xsolla config list --json). If it points elsewhere, switch it (xsolla config set merchant-id, project-id, sandbox false) and say so, with the undo.
  • The batch. One row per payment provider page, as the manifest's batch.row_example shows: provider (lowercase URL segment), partner_name, optional partner_logo_url, hero_title (at most 60 characters), hero_description (at most 150), hero_image, faq, optional offers, and optional seo_title / seo_description (default: the hero title and description). The rows are {"providers": [...]}. Game data never goes in the batch: it is bound, never typed.

Steps

All scripts are in scripts/ and run with python3 -I. Keep each run's files in a new .xsolla/xla-<UTC time>/ folder.

  1. Preflight. Run preflight_report.py next --pub-dir <run>/pub. GET each URL it prints and save the response as is, with the time of the request, in the format saved /pub responses gives. Only GET, only https://xla-pages.xsolla.com/pub/*, no credentials. Repeat until it prints none, then run preflight_report.py report --pub-dir <run>/pub --batch <batch.json>.
  2. Backup. backup.py --out-dir <run>/backup saves the skill's own get-structure and get-localization snapshot. It is the backup: Shop Builder's version history isn't, because restoring a version currently drops the data-provider connections.
  3. Plan. render_plan.py --batch <batch.json> --backup-dir <run>/backup --output <run>/plan.json. It pins every block to the version on its page type's reference page and refuses a row over the limits, a field the reference block doesn't have, or anything the manifest doesn't list. Then cli_gate.py --plan <run>/plan.json says whether the CLI can apply it.
  4. One approval. Show, in one message:

    • every page that appears or changes: create, update or unchanged, its route and type, its blocks with versions in order, its bindings, the row text word for word, SEO and page look;
    • for each existing page, what differs from the manifest now (differences_now), and the plan's notes;
    • the preflight: its lines, the redirect list per provider, and the request times;
    • the gate's result: which writes the CLI can make today;
    • that the Pages team publishes this site themselves, and their next publication ships these draft changes to x.la.

    Ask for one explicit yes. A request to "create the pages" is not that yes. When cli_gate.py reports missing commands, or the plan's updates_off is set, show the plan and the reason, say that nothing can be written until that changes, and don't ask for the yes.

  5. Apply. apply_pages.py --plan <run>/plan.json --confirmation-id <its confirmation_id> --backup-dir <run>/backup --pub-dir <run>/pub. Before the first write it stops, with zero writes, on: an edited plan, another backup, any manifest violation, /pub responses older than 24 hours or incomplete, the wrong CLI target, a missing command or flag in --help (blocked_capability), updates that aren't allowed yet (updates_off), another or a published site the config doesn't allow, or a site that changed since the backup. It deletes the blocks add-page seeds on a page it created in the same run (deleted, not hidden), and sets a page's look only to the reference page's values.
  6. Check and hand off. Apply reads every page back and prints the per-page result: pass, or the exact difference, plus the manifest's acceptance numbers. For an update it checks that the page's data bindings are identical before and after. verify_pages.py --plan --structure --localization --backup-dir runs the same check on any export. Report every page, the numbers, and that nothing was published: a person publishes, all pages of the site at once.

When something changes

  • Responses older than 24 hours: request them again (step 1); the plan stays valid. Quote the report's fresh_until time; don't work it out.
  • The site changed after the backup (the Pages team edits it too): back up again, render again, show the new plan, and ask again.
  • A run that stopped partway prints what it created (created_pages, created_blocks). Show them and offer two ways on: back up, render (created pages now show as updates), show the plan and ask again; or a person deletes them in the Editor. The skill doesn't delete them or restore a version. Never retry blindly.
  • An existing page that differs from the manifest: an update writes only row content, settings, an empty optional block's hidden flag, static SEO text and the page look. Missing bound blocks, extra blocks, wrong versions and bindings are listed for a person; blocks that were on a page before the run are never deleted or moved.

Hard stops

  • Never publish, enable a preview, run verify-website, or apply or restore a site version.
  • Never write to the catalog, LiveOps or the XLA Pages API; the preflight only reads /pub.
  • Never add a standard Shop Builder block, a Custom Block, a Custom code block, a block script, styles, fonts, iframes or trackers; never type game data into a block.
  • Never pass --force; never call a command outside scripts/xla_common.py's list.
  • Never write to a site other than the configured one, or to a copy of it.
  • Never commit .xsolla/, a plan, a backup or saved responses: they hold real IDs.

Known limits

The manifest's block field names, the @xla-pages blocks' ids in the blocks service, and the published-site semantics are not verified against a real site yet; README.md lists every unverified item. Read-back shapes the CLI doesn't return yet make the check fail, not pass.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.