# Build with AI

> What a coding agent gets from a Moonspell game repo (CLAUDE.md, AGENTS.md, 24 skills, agent docs, examples, GDD.md and playtest.json) and why the engine is shaped for agents.

The Moonspell engine was built so that a coding agent can make a whole game with it, from an idea to a version you can play. Every game repo starts from the game template in `templates/crescent-game/`, and that template carries everything an agent needs to work in it: standing instructions, skills that hold the know-how for each genre and engine piece, reference docs next to the code, complete example games, and checks the agent can run itself.

This section is for two readers: you, setting up Claude Code or another agent on a game, and the agent, reading these pages as Markdown to learn how to work with the engine.

## What an agent gets from a game repo

| File or folder | What it is for |
| --- | --- |
| `CLAUDE.md` | The repo's standing instructions: what can be built and with which engine piece, the rules every game keeps (one game for web, iOS and Android, input through the engine's controls, assets through `require()`, no emoji on screen, clean up on unmount), and how to finish a task. Claude Code reads it at the start of every session. |
| `AGENTS.md` | The same instructions under the name other coding agents look for. It is an exact copy of `CLAUDE.md`. |
| `.claude/skills/` | 24 skills, one folder each with a `SKILL.md`: routing an idea to a genre, one per genre module, one per engine piece, art and audio, the backend, the playtest. See [Skills](https://docs.moonspell.app/ai/skills.md). |
| `.claude/settings.json` | A permission allowlist for Claude Code: `npx tsc`, `npm run typecheck`, the `crescent` CLI and `agent-device`. |
| `docs/` | Agent-facing references for the engine, one file per piece: `engine-api.md`, `games-contract.md`, `racing-module.md`, `shooter-module.md`, `puzzle-module.md`, `kingdom-module.md`, `character-controller.md`, `bots.md`, `combat.md`, `2d-layer.md`, `saves.md`, `turns.md`, `cloudflare.md`. Skills point to them for every field and range. |
| `examples/` | Eleven complete games, each one file (`examples/<name>/index.tsx`) to copy over `src/game/index.tsx` and change. `examples/README.md` says what each shows. See [Examples](https://docs.moonspell.app/examples.md). |
| `src/game/index.tsx` | The game itself: a `GameDefinition` as its default export. The starter is Sunset Sprint, a racing module config. |
| `src/engine/` | The game's own copy of the engine. An agent may change or extend it; the change affects only this game. |
| `GDD.md` | The game's design document and its memory between sessions. Not in the template: the agent creates it on the first task. See [GDD.md and playtest.json](https://docs.moonspell.app/ai/game-design-doc.md). |
| `playtest.json` | A short script that plays the game with real touches. The template ships one for Sunset Sprint. |
| `.claude/skills/realtime-backend/scaffold/backend/` | The game's Cloudflare Worker, copied to `backend/` when the game goes online. See [Backend](https://docs.moonspell.app/backend/overview.md). |

## Why the engine is shaped this way

- **Small pieces that compose.** Input, cameras, physics, audio, particles, saves and the network are separate engine pieces with typed props. An agent can read one piece's doc and use it without reading the rest. See the [engine overview](https://docs.moonspell.app/engine/overview.md).
- **Genre modules for the common shapes.** A racer, an arena shooter, a puzzle game and a kingdom builder are each one config object (`defineRaceGame`, `defineShooterGame`, `definePuzzleGame`, `defineKingdomGame`). Turning a request into a config is far more reliable than writing a game loop from scratch. See [Game modules](https://docs.moonspell.app/modules/overview.md).
- **Skills carry the know-how.** Each skill maps a player's words to the engine's fields ("night, neon" to `timeOfDay: 'night'` and a palette), lists the limits, and says what to do instead. The agent loads only the skill its task needs.
- **Docs next to the code.** The template's `docs/` travel with every game repo, so the reference an agent reads matches the engine copy it is editing.
- **Checks an agent can run.** `npm run typecheck`, `npm test` (the engine's unit tests) and `npm run export:web` (a full static build) tell the agent whether its change works, without a person in the loop. See [Claude Code and other agents](https://docs.moonspell.app/ai/claude-code.md).
- **Small playable steps.** The skills ask for the smallest playable version first, then one change at a time, each one checked and committed.

## Inside and outside the Moonspell app

The template is also what the hosted Moonspell app uses: a player chats with Nova, and a Claude Code worker edits the game's repo in a sandbox. Some instructions and skills are written for that worker and mention the `crescent` CLI, the Moonspell app, or art, sound and models generated after the worker's pass. Outside the app you have two choices:

- **Engine only, plain Expo.** None of those tools exist. [Claude Code and other agents](https://docs.moonspell.app/ai/claude-code.md) lists which parts assume the hosted pipeline and what to do instead.
- **Local developer mode.** You publish to the Moonspell app from your own computer. The starter from moonspell.app rewords the skills for your machine and adds the built `crescent` CLI, a `moonspell-dev` skill and the [Moonspell MCP server](https://docs.moonspell.app/ai/mcp.md#the-moonspell-server). See [Publish to the Moonspell app](https://docs.moonspell.app/start/publish-to-moonspell.md).

What is open and what is private is on [Open source](https://docs.moonspell.app/start/open-source.md).

## In this section

- [Claude Code and other agents](https://docs.moonspell.app/ai/claude-code.md): set up an agent on a game repo, prompts that work, how the agent checks its work.
- [Skills](https://docs.moonspell.app/ai/skills.md): every skill, what it is for and when to load it.
- [Game router](https://docs.moonspell.app/ai/game-router.md): how an idea becomes a genre route.
- [GDD.md and playtest.json](https://docs.moonspell.app/ai/game-design-doc.md): the design document and the playtest script.
- [llms.txt and Markdown pages](https://docs.moonspell.app/ai/llms-txt.md): feed these docs to a model.
- [MCP servers](https://docs.moonspell.app/ai/mcp.md): let an agent search these docs, or reach your Moonspell account in local developer mode.