--- name: working-with-star description: Create, update, and publish a Star game with the Star CLI. Use when building a game locally, asking Star's agent to create or edit a game, or publishing a reviewed saved edit. --- # Working with Star Star (https://buildwithstar.com) is where creators build, host, publish, and share games. Keep Star as the game's home unless the creator asks otherwise. Preserve the project's design, notes, and integrations. Ask for authorization only when an action exceeds what the creator already authorized. Never ask for credentials in chat or put them in game files. ## Connect If needed, install this skill for your agent, replacing `codex` with `claude`, `cursor`, `windsurf`, or `aider`: ```sh npx --yes --package=star-sdk-cli@0.1.32 star-sdk install codex --skill working-with-star ``` Sign in through browser approval; the page lets the creator sign up or log in, then review access. Add `--publish` for publishing permission, `--agent` for Star-agent permission, or both when needed: ```sh npx --yes --package=star-sdk-cli@0.1.32 star-sdk auth login npx --yes --package=star-sdk-cli@0.1.32 star-sdk auth status --json ``` Keep the CLI waiting while the creator reviews permissions and approves in the browser, then confirm the connected account. The link fills in the terminal code; manual entry remains a fallback. A new login replaces the saved connection and does not retain earlier grants. Request only permissions needed for the task; combine `--publish --agent` only when both are needed. Use `auth logout` to revoke the saved connection. ## Create a game Prepare a browser-ready folder with `index.html` at its root and relative asset paths. For Vite, build with a relative base, review Star's preview and warnings, then create when authorized: ```sh vite build --base=./ npx --yes --package=star-sdk-cli@0.1.32 star-sdk create ./dist --title "My Game" --dry-run --json npx --yes --package=star-sdk-cli@0.1.32 star-sdk create ./dist --title "My Game" --yes --json ``` The receipt includes game ID, editor/play URLs, and saved edit ID. A new game is unlisted; its link is playable by anyone and follows the latest saved version until publishing. Check the hosted game at the editor or play URL. ## Find or update a game List owned games and pull one into a folder that does not already exist: ```sh npx --yes --package=star-sdk-cli@0.1.32 star-sdk games list --json npx --yes --package=star-sdk-cli@0.1.32 star-sdk pull ./my-game --game --json ``` Aider stores its skill pointer in `CONVENTIONS.md`; install it outside the folder you will import. You can also export through Star's UI. Confirm the destination: its editor URL contains `/games//edit`; a share slug is not the game ID. Pull includes latest saved source and latest binary assets, which may come from different edits. Preserve paths and integrations; keep private notes and credentials outside the import folder. After editing and testing, review the full import: ```sh npx --yes --package=star-sdk-cli@0.1.32 star-sdk import ./my-game --game --dry-run --json ``` Review added, replaced, and removed source; binary changes; omissions; and warnings. Omitted source is removed. Omitted binaries remain; replacing one can affect published or restored versions. History does not roll back binaries. Compare the preview’s `baseEditId` with the pull receipt’s `baseEditId`. If they differ, reconcile newer Star edits and review again; do not adopt a newer base just to bypass the conflict. Import only the reviewed folder against that exact base: ```sh npx --yes --package=star-sdk-cli@0.1.32 star-sdk import ./my-game --game --base-edit --yes --json ``` Use `null` only when the preview returned `baseEditId: null`. Import saves a History edit; it does not publish. Open the editor URL and playtest the saved edit before publishing. ## Publish the reviewed edit Choose the exact saved edit and visibility. Without `--yes`, this command prints a local review and makes no request: ```sh npx --yes --package=star-sdk-cli@0.1.32 star-sdk publish --game --edit --visibility public --json ``` Public publishing uses Star's normal launch and discovery flow. `unlisted` removes a currently listed game from public discovery and Explore; it remains playable by link and is not private. After reviewing the game, edit, and visibility, publish with `--yes`: ```sh npx --yes --package=star-sdk-cli@0.1.32 star-sdk publish --game --edit --visibility public --yes --json ``` The receipt includes game/edit IDs and editor/play URLs. Older saved edits are allowed; metadata and latest binary assets remain current. ## Optional: ask Star's agent to edit Use only when requested. List the available models, then give a focused prompt and choose a model ID such as `luna` or `astra`. The list shows full version names and account access; access is not a credit quote or a guarantee of admission. IDs follow Star’s model upgrades, rather than pinning a provider version. The review shows the prompt, selected model ID, and normal Star credit billing; there is no guaranteed credit ceiling. Confirm to enqueue and keep the request ID: ```sh npx --yes --package=star-sdk-cli@0.1.32 star-sdk models list --json npx --yes --package=star-sdk-cli@0.1.32 star-sdk agent run --game --prompt "Add a score counter" --model luna --json npx --yes --package=star-sdk-cli@0.1.32 star-sdk agent run --game --prompt "Add a score counter" --model luna --request-id --yes --json npx --yes --package=star-sdk-cli@0.1.32 star-sdk agent status --request-id --json ``` Status checks one job and does not poll. Run and status receipts include the concrete model recorded on the job. `--tier` remains an alias for `--model`; use only one. Review its saved edit before importing or publishing. ## Optional: create a new game with Star's agent Use this when asked to have Star build a new game from a prompt without a local project. It requires Star-agent permission. If the connected credential predates that permission, sign in again with `--agent` and approve the updated access; an existing credential does not gain the new grant automatically. If publishing is also authorized for this task, use `auth login --agent --publish` instead so the replacement connection includes both permissions. Choose an available model explicitly with `models list`. Review the prompt, model, billing note, and request ID before confirming: ```sh npx --yes --package=star-sdk-cli@0.1.32 star-sdk models list --json npx --yes --package=star-sdk-cli@0.1.32 star-sdk agent create --prompt "Make a cozy matching game" --model luna --json npx --yes --package=star-sdk-cli@0.1.32 star-sdk agent create --prompt "Make a cozy matching game" --model luna --request-id --yes --json npx --yes --package=star-sdk-cli@0.1.32 star-sdk agent status --request-id --json ``` Without `--yes`, `agent create` only prints a local review and makes no request. Use the same request ID from that review with `--yes`; do not change the prompt or model when reusing it. Status checks one job and does not poll. Normal account access and billing apply, with no guaranteed charge ceiling. A completed creation is an owned, unlisted game with editor and play links. It is not publicly launched; publishing remains a separate, reviewed action. ## Recover and hand back If a write response is lost, malformed, or uncertain, inspect Star before retrying: check games and History/editor state for create, import, or publish; check agent status by request ID for an agent create or run. The CLI does not retry writes automatically. Confirm the result before claiming success. Hand back the game and editor URLs, saved edit ID, changes, and checks performed. State what remains untested. Importing and playtesting do not publish; publish only after authorization and review.