Skip to main content

The xgenia-mcp Skill

Early Alpha

The XGENIA MCP server is in early alpha. See Driving XGENIA from Claude Code for install and setup.

The MCP server gives an agent hands on the editor. The skill is what stops it using them badly.

It lives at plugins/xgenia/skills/xgenia-mcp/ in the XGENIA repo; copy it to ~/.claude/skills/ — see Install, and note that the marketplace install gives you the skill but not the tools. Claude Code loads a skill when the work matches its description — "use XGENIA", "build a game in XGENIA", "send a prompt to the XGENIA chat", "XGENIA is stuck" — or you can ask for it directly with /xgenia-mcp.

What it adds on top of the tool schemas:

  • The call sequence — which tool answers a question, and in what order.
  • The cost rule — check the model before any run longer than a couple of turns.
  • The traps below, each of which makes a working call look like it failed.
  • How to tell whether a change to the panel actually reached the running editor.

Traps that make a working call look broken​

A send that "may not have been sent" usually was​

xgenia_chat_send confirms by watching for the input to clear and the prompt to appear in the transcript. Both signals lie, in different directions:

  • The input is contenteditable, so an unsent prompt is in the frame's body text too.
  • data-empty has been observed false on a send that had already landed and was being answered.

Current behaviour reads the input's own text separately, so a match in the body while the input no longer holds it proves the send. When it still comes back unconfirmed, the error code tells you which case you have — render-lag means read, don't resend; not-submitted means resend is safe. See the tool reference.

Prompts that name nodes​

XGENIA prompts refer to things as @Paytable, @GameState, @SpinCalc. The panel opens a mention autocomplete on @.

Typing character by character let that autocomplete swallow the rest of the prompt into a mention chip and eat the Enter. Nothing was sent, twice, and only the contents of the input showed why. The harness now inserts the whole string as a single input event and presses Escape before Enter. On an older server build, avoid @ in prompts, or check the input after sending.

Screenshot coordinates​

imageSize is the buffer; contentSize is the page. Convert through scale from the same response, and treat anything beyond contentSize as empty space rather than as editor UI that failed to render.

scale was wrong before 2026-09-06 — it reported 1.2503 where the truth was 1.0, because it measured the blank margin and called it zoom. On an older build, measure against a known element rather than trusting it.

busyForMs is a floor, not a duration​

Measured from the server process's first sight of the busy state. A panel stuck for hours reads the same as one that just started.

Deploying while a turn is in flight kills the turn​

Shipping the Chat panel or its backing function mid-generation produces Failed to fetch or AI Communication Error in the transcript. That is the deploy, not an XGENIA bug. Wait for idle before shipping, or expect to re-send.

Recovery​

SymptomCall
not-runningxgenia_launch
editor-unresponsive — wedged rendererxgenia_restart with force: true, which skips the connect and every in-page read and goes straight to the kill
Chat stuck generating foreverxgenia_restart, or xgenia_chat_send with force: true if the panel is otherwise fine
not-authenticatedStop and tell the user. A human signs in once, in the editor. There is no tool, flag or environment variable that types, stores or reads a password
selector-missingxgenia_probe — the Chat panel deploys independently of XGENIA releases, so selectors move

After a restart, check recoveryError, declinedPorts, save.confirmed and hardKilled before assuming it was clean — a restart can succeed and still have lost something.

Verifying a change actually reached the editor​

The Chat panel is served separately and iframed by the editor. Editing its source locally changes nothing you can observe until it has been built, deployed and reloaded. Three checks, in order:

  1. Deploy it, with whichever command re-points the production alias — not just a preview build.
  2. Confirm the bundle reached the edge. Fetch the deployed page and match the bundle hash against what the deploy expected. A mismatch immediately after a deploy is usually CDN lag; re-check in 30–60 seconds.
  3. Reload the panel. xgenia_restart, then exercise the changed behaviour and read the result out of the transcript.

Skipping step 3 is how a "verified" fix turns out to have been tested against the old bundle. The panel also shows an opt-in "A new version of the AI panel is available — Reload" banner; it does not hard-reload mid-use.

The MCP server itself is different

It is a local process started when the session began. Rebuilding it does not affect the running session — the client has to be restarted to pick up a new build. If you have just fixed the harness, say so rather than claiming the fix is live.

Judgement while driving a build​

  • Watch, do not just wait. Poll xgenia_chat_read during long runs and stop a run that is going astray, rather than paying for it to finish.
  • Ask for evidence, not reasoning. The panel's AI will state a confident mechanism it has not checked. Ask it to run its own timeline and execution-status tools and report what actually executed. It retracts cleanly when shown runtime evidence — and a retraction under evidence is a sign the earlier claim was invented, not a reason to trust the next one more.
  • A fix is not verified by arithmetic. If a tool reported a number before a change, do not accept a calculated number after it. Make the tool print the new figure.
  • Screenshot when the text is ambiguous. region: "chat" for the conversation and the model footer, canvas for the graph, full for the whole window.