Getting started

Inspecting, scaffolding and validating a manifest need no account. dev and verify do, because they run a real Engine: gamestage login signs you in, or creates one the first time.

Install the tool, scaffold a game, sign in, play it against a real Engine, then read what verify says about it.

1. Point your agent at Gamestage

npx skills add https://gamestage.ai/skill

That runs skills, Vercel Labs' open installer, from npm. It finds the coding agents you have and copies one Markdown file into each one's own skills folder, .claude/skills or .codex/skills. This command does not change your CLAUDE.md, your AGENTS.md or your Cursor rules, and it asks whether to install for this project or for your user account. Run it again to update them.

The same pack is on GitHub, if you would rather install from there or read it before you install anything:

npx skills add gamestageai/agent-skills

Both commands write the same file. The repository also carries a worked example of each game format, at github.com/gamestageai/agent-skills.

To choose the agents yourself, add -a claude-code, or -a codex, or both.

To install nothing at all, tell your agent to read gamestage.ai/skill and follow it. That is the same file, served as Markdown, and it needs no permission from anybody.

The tool itself comes from npm each time you call it:

npx gamestage start

You need Node 20 or newer. npx gamestage doctor checks the rest of your environment and says what is missing.

Keeping it current

npx caches, so npx gamestage can keep running a version you downloaded weeks ago. npx gamestage@latest <command> always fetches the current one.

This matters because a stale tool does not look stale. It looks like the documentation is wrong: a command refuses something this page says it accepts, and the only difference is the age of the bundle. gamestage start prints the version it is, so compare that against the current one before assuming a page here is wrong. Nothing checks for you: the CLI never calls home.

If you would rather have the file on disk

curl -fsSL https://gamestage.ai/cli -o gamestage.mjs
node gamestage.mjs start

One file on disk that executes nothing until you run it. It is also the one route that never updates itself, so re-run the curl when the version start prints has fallen behind. There is also a shell installer at /install that puts a gamestage command on your PATH and writes the agent instructions in the same step. Read it before you run it. No page promotes it, because the two npx commands above need no install at all.

Every example below says gamestage <command>. Whichever route you took, that means the tool you installed: npx gamestage <command>, gamestage <command> or node gamestage.mjs <command>. The tool knows how it was started and prints back the form that works for you.

2. Read what your agent reads

The agent does the migration, and the CLI inspects, serves and proves it worked. Step 1 wrote the instructions for you. To wire an agent by hand, the text is at /agent.md, with the fuller entry point at /start.md. Both are plain Markdown, written to be read once.

Every chapter of this documentation is also served as raw Markdown and JSON: add .md or .json to any docs URL.

3. Make something small first

gamestage formats
gamestage create --name "My Game" --format hunt
cd my-game          # only if create says it made a folder
gamestage login
gamestage dev --serve

formats says what each format is, with a game of that kind to play, so you choose knowing what you get. create writes gamestage.yaml, an index.html, the two generated browser clients and a favicon; run by hand with no flags it asks for the name and the format instead. In a folder that already holds other things it makes a folder named after the game. login creates the account dev and verify need, or signs you back into one you already have. dev --serve plays the game on your machine with a sample round, through the same Engine rules the hosted service runs, and prints the address to open. Play it and get one wrong. The attempts come down because the Engine said so, and the page draws what it was told.

create scaffolds a playable page for hunt, push, group, predict, bingo and shoot. Read Game formats for the detail. A format we do not have yet: gamestage suggest "what you want to build".

Then prove it:

gamestage verify

verify exits 0 only when every check passes. Any other number means something is open or unproved, and the output says which.

4. Bring your own game

If you already have a prototype, start by letting the CLI read it:

gamestage inspect . --write

Source inspection is read-only. --write adds gamestage.yaml and refuses to replace an existing one unless --force is present. The report separates what stays in the interface, what has to move behind the Engine, what platform support is missing, and what needs a person to decide.

From there, follow Build and deploy, which is the same route in detail.

Constraints

Inspecting, scaffolding and validating a manifest need no account. dev, verify and deploying do: gamestage login creates one, somebody at Monterosa approves it, and from then on the hosted route runs on the CLI's defaults.