# Skills

> Every skill in the game template's .claude/skills folder, grouped by job, with what it is for, when an agent should load it, what it produces, and which ones assume the hosted Moonspell pipeline.

A skill is a folder in `templates/crescent-game/.claude/skills/` with a `SKILL.md`: a short front matter (`name`, `description`) and the instructions for one job. Claude Code matches a task to a skill by its description and loads only that one. Other agents can read the file directly. Some skills have reference files next to `SKILL.md`.

The template has 24 skills. Start with **game-router** for any new game or change of genre; it names the next skill to read.

Skills marked **hosted** were written for the Moonspell app's worker and use tools that do not exist outside it. What to do instead is on [Claude Code and other agents](https://docs.moonspell.app/ai/claude-code.md#what-assumes-the-moonspell-app).

## Routing and design

| Skill | What it is for | Load it when | What it produces |
| --- | --- | --- | --- |
| `game-router` | Maps the player's words to a genre and a route: a module config, an example to copy, or from scratch, with the camera, controls, bots and online defaults for that genre and what is not possible yet. | First, for any request that creates a game or changes what kind of game it is. | A route (`module:racing`, `foundation:character`, `kit:turns`, `scratch`...) written as one line in the commit message. See [Game router](https://docs.moonspell.app/ai/game-router.md). |
| `crescent-game-change` | The procedure for any change: read `GDD.md`, route, read before writing, the smallest change that does what was asked, game UI, phone rules, verify, commit. | Every task in a game repo. | A checked, committed change. Its verify step uses `crescent export`; outside the app use `npm run export:web`. |
| `game-design-doc` | Creates, reads and grows `GDD.md`: pitch, pillars, controls, a table of dynamics (trigger, move, camera, world, sound), rules, assets. Also how to read a reference video into moments with `ffmpeg`. Reference file: `gdd-template.md`. | Start of every task; whenever someone gives a reference video, image or game to match. | `GDD.md` at the repo root, updated in the same commit as the code. See [GDD.md and playtest.json](https://docs.moonspell.app/ai/game-design-doc.md). |

## Genres

| Skill | What it is for | Load it when | What it produces |
| --- | --- | --- | --- |
| `car-race-game` | Vibe words to a `defineRaceGame` config: time of day, scenery, track preset or custom points, car tuning, opponents, post-processing look. | The game is or becomes a car race (`module:racing`). | A race config in `src/game/index.tsx`. See [Racing](https://docs.moonspell.app/modules/racing.md). |
| `shooter-game` | Words to a `defineShooterGame` config: mode (`ffa`, `tdm`, `gun-game`, `ctf`, `koth`), map, loadout, bots, pickups, multiplayer. | The router picks `module:shooter`. | A shooter config, started from `examples/flag-rush/`, plus the `<id>-kills` board for the backend. See [Arena shooter](https://docs.moonspell.app/modules/shooter.md). |
| `puzzle-game` | Words to a `definePuzzleGame` config: pack (`block`, `merge`, `match`, `sort`), mode, difficulty, theme, drawn tiles, sounds. | The router picks `module:puzzle`, and every change to a puzzle game. | A puzzle config from `examples/moon-blocks/` or `examples/moonrise/`. See [Puzzle](https://docs.moonspell.app/modules/puzzle.md). |
| `kingdom-game` | Words to a `defineKingdomGame` config: theme, buildings on timers, crops, hero classes, missions, and the required story chapters. | The router picks `module:kingdom`, and every change to a kingdom game. | A kingdom config from `examples/oath-of-ashvale/`, plus model and cut-out lists. See [Kingdom](https://docs.moonspell.app/modules/kingdom.md). |
| `character-game` | Words to a level, character params, camera, touch controls, bots and weapons on the character foundation: parkour, arena, tag, stealth, horror, top-down, side-view, melee. | The router picks `foundation:character`. | A game copied from `examples/rooftop-hop/`, `examples/lantern-tag/` or `examples/pulse-arena/` and changed. See [Character and cameras](https://docs.moonspell.app/engine/character-and-cameras.md). |
| `platformer-2d` | Flat 2D platformers, side-scrollers, runners and top-down games on the 2D layer: tile maps from strings, the platformer and top-down controllers, triggers, parallax, animated sprites. | A side-scrolling run-and-jump game, a 2D dungeon or maze. | A game started from `examples/sky-runner/`. See [2D layer](https://docs.moonspell.app/engine/2d.md). |

## Engine pieces

| Skill | What it is for | Load it when | What it produces |
| --- | --- | --- | --- |
| `touch-controls` | The multi-touch rules every control follows: one gesture tracks every finger, no separate `Pressable`s for buttons held together, no window coordinates. Also `<CharacterControls secondThumb />`. | Adding or changing any control or HUD button. | Controls that take several fingers at once. See [Input](https://docs.moonspell.app/engine/input.md). |
| `game-ui` | Screens, look and feel: the screen set (title, HUD, pause, results), palette and shapes from the game's theme, one font family from the genre picker, SF Symbol icons through `<Icon>` (never emoji), juice. Reference file: `juice.md` (button, banner, counters, results, coin fly). | Every new game, and any screen, menu, HUD element, button, banner or reward. | UI that matches the game, checked against its "Before you save a checkpoint" list. See [HUD and UI](https://docs.moonspell.app/engine/hud-and-ui.md). |
| `expo-animation` | Sub-skill of `game-ui`: how to build any React Native animation (should it animate, which thread, which properties, spring or timing, haptics, reduced motion) with Reanimated 4 and Gesture Handler. Vendored from expo/skills under MIT (`LICENSE`); a block at the top adapts it to games. Reference file: `RECIPES.md`. | Writing animation code for menus, HUD pieces, panels or drags, or when motion stutters. | Animations on the UI thread using the engine's motion constants. |
| `game-feel` | 3D moments: `shake`, `hitStop`, `slowMotion`, `flash`, `squash`, `stretch`, `pop`, `vanish`, tweens and the `juice()` presets under `<GameFeel>` and `<FeelOverlay>`. | Hits, landings, pickups, explosions, deaths, or a game that "feels flat" in 3D. | Juice in the scene. See [Game feel](https://docs.moonspell.app/engine/game-feel.md). |
| `gpu-effects` | TypeGPU particles (`fire`, `sparks`, `smoke`, `magic`, `rain`, `snow`, `dust`, `vortex`), trails, and your own compute shaders on three's device. | Fire, explosions, magic, weather, exhaust, bursts, or thousands of moving things. | `<Particles>` and compute code. See [GPU effects](https://docs.moonspell.app/engine/gpu-effects.md). |
| `physics` | Rigid bodies on cannon-es for the few objects that matter, GPU debris for the many small ones, triggers, joints, `<Vehicle>`, with a budget and when to leave physics off. | Things that are knocked over, thrown, dropped, rolled, swung, scattered or picked up. | `<Physics>` with bodies. See [Physics](https://docs.moonspell.app/engine/physics.md). |
| `saves` | Progress players come back to: `defineSave`, `defineProgression` (currencies, shop, unlocks, XP, daily streaks, offline earnings), `useSettings`, `<ScoreCard>`, and how to test migrations. | The game keeps anything between sessions, or the player asks for a shop, upgrades, levels, daily rewards or a settings screen. | An engine save that syncs once a backend exists. See [Saves](https://docs.moonspell.app/engine/saves.md) and [Saves sync](https://docs.moonspell.app/backend/saves-sync.md). |
| `native-now-modules` | Every native module compiled into the Moonspell app, by category, with exact versions. Reference file: `references/modules.md`. **Hosted**: written for the prebuilt shell (`crescent catalog`, `crescent doctor`). | Choosing a library, or before adding any dependency. | A library choice from the pinned set. |

## Art and audio

| Skill | What it is for | Load it when | What it produces |
| --- | --- | --- | --- |
| `models` | 3D models for characters, vehicles, buildings and props, used through `<Model>`, `CharacterMesh model=` and `<Scenery>` with a fallback; prompts that rig well; the budget. **Hosted**: the files are generated after the agent's pass from `~/.crescent/models.json`. | A specific look (a knight, a red kart, a street of buildings), or capsules and boxes that should become real shapes. | Fallback-first model code and a model list. See [Models and scenery](https://docs.moonspell.app/engine/models-and-scenery.md). |
| `sprites` | 2D art: character sheets, items, tilesets, backgrounds and parallax layers, used through `createSheet` with your shapes as the fallback. **Hosted**: drawn after the pass from `~/.crescent/sprites.json`. | A 2D game that should look like more than flat shapes, or a named look (pixel art, a cute fox). | Sheet code with fallbacks and a sprite list. |
| `cutout-art` | Cut-out items in a pre-rendered 3D look (resource icons, rewards, build cards, portraits, crops) used through `<SheetImage>` in the HUD and `<Billboard>` in the scene. **Hosted**: drawn after the pass from a `cutouts` entry in `~/.crescent/sprites.json`. | Item pictures or story portraits instead of icons. | Cell-indexed art with fallbacks. |
| `sound-design` | The whole sound of a game: list every sound from the GDD's dynamics (body, reactions, rewards, air, music), write prompts, clean files with `ffmpeg`, wire them through `useAudioMixer`. Generation is **hosted** (Seed Audio for `.wav`, Sonilo for `.m4a`, after the pass). | Every new game, every new move or moment, and any request for music, effects or ambience. | A sound plan in `GDD.md` and mixer wiring. See [Audio](https://docs.moonspell.app/engine/audio.md). |

## Backend

| Skill | What it is for | Load it when | What it produces |
| --- | --- | --- | --- |
| `realtime-backend` | The game's Cloudflare Worker: live leaderboards, presence, multiplayer rooms joined from a link, ghosts and spectating, synced saves, the computer opponent (`POST /ai/turn`), and anything that should outlive the phone. Includes the scaffold in `scaffold/backend/` and its `CLAUDE.md`. Its setup steps are **hosted** (a gateway and MCP tools); the scaffold and client code are not. | Any online, shared, multiplayer, high-score or AI-character request, and any change to `backend/` or `src/engine/net`. | `backend/` copied from the scaffold, `BOARDS` filled in, `GAME_BACKEND_URL` set. See [Backend](https://docs.moonspell.app/backend/overview.md). |

## Testing and shipping

| Skill | What it is for | Load it when | What it produces |
| --- | --- | --- | --- |
| `playtest` | Writes and keeps `playtest.json`, a script of real touches (`press`, `hold`, `tap`, `drag`, `expect`, `expectChange`, `mark`, `repeat`). **Hosted**: the Moonspell pipeline runs it on a simulator and its recording becomes the game's feed video. | Every new game, and whenever screens, button labels or controls change. | `playtest.json` at the repo root. See [GDD.md and playtest.json](https://docs.moonspell.app/ai/game-design-doc.md). |
| `push-to-device` | `crescent push`: re-export and send the bundle live to a connected Moonspell app, and read its exit codes. **Hosted** only. | A person developing with a Moonspell app connected to a local `crescent start` server. | Nothing outside the Moonspell app: run `npm run web` or a development build instead. |

## Adding a skill

A skill for a new genre module also needs a row in the `game-router` skill (trigger words in Classify, a row in Route, the limit removed from section 3) and a line in the template's `CLAUDE.md` skills list. See [Writing a module](https://docs.moonspell.app/modules/writing-a-module.md).