Claude Code skills for game development: a setup

Claude Code is the tool creators name most often in our catalog, on 169 of 404 games. This guide is for the next game, where you want the agent to know your project on day one and to check its own work without being asked.

Four pieces do that: project memory, skills, hooks and subagents. Commands and file names below come from each tool’s documentation as of September 2026, linked where they appear.

The four pieces and what each is for

Piece	Where it lives	Loads	Use it for
CLAUDE.md	project root	every session	how to run, test and build; rules that apply to every task
Skill	.claude/skills/<name>/SKILL.md	when a task matches, or on /name	a job you repeat: playtest, balance pass, new enemy
Hook	.claude/settings.json	on an event, every time	checks that must not be skipped: format, test, block
Subagent	.claude/agents/<name>.md	when delegated	a second pair of eyes with its own context: review, asset audit

The split matters because context is the budget. CLAUDE.md costs tokens in every session. A skill costs about a hundred tokens for its name and description until it runs, according to the Agent Skills specification. A hook costs nothing until its event fires.

Write a CLAUDE.md that fits on one screen

Anthropic suggests keeping each CLAUDE.md under 200 lines, and /init drafts one from your repo (memory docs). For a game, five lines carry most of the value. Say how to run it and how to test it. Say where the tuning numbers live, what the agent must not touch, and how to know a change worked.

# My game: Three.js and Vite

- Run: `npm run dev`, then open http://localhost:5173
- Test: `npm test` (Vitest, game logic only, no browser)
- Tuning numbers live in `src/config/balance.json`, never in code
- Never edit `public/assets/` by hand: `npm run assets` builds it
- Done means: tests pass, the game loads with no console errors, and a
  60-second round is playable with keyboard and touch

Two habits make a game easier for an agent to change and test. Keep tuning values in a data file, so “make the second level easier” is a one-line diff instead of a hunt through physics code. And keep game logic testable without a browser. A fixed timestep, as Glenn Fiedler describes in Fix Your Timestep, plus a seeded random generator, makes a round replayable in a test.

Longer notes go in .claude/rules/*.md files with paths: in their front matter, which load only when Claude reads matching files (memory docs). Level design notes can wait until someone opens a level file.

Turn a prompt you keep pasting into a skill

A skill is a folder with a SKILL.md. The spec requires two fields, name (lowercase, hyphens, same as the folder) and description, and suggests keeping the file under 500 lines (spec). Claude Code reads project skills from .claude/skills/, and every skill doubles as a slash command (skills docs).

Anthropic’s docs suggest a skill when you keep pasting the same instructions, checklist or multi-step procedure into chat, or when part of CLAUDE.md has grown into a procedure. For games, three are worth writing first.

A playtest skill

---
name: playtest
description: Play the game in a browser and report bugs. Use after a
  gameplay change, or when the user asks to playtest or check the game.
---
1. Start the dev server with `npm run dev` if it isn't running.
2. Open the game, wait for the first frame, read the console.
3. Play one round: move, jump, collect, lose once on purpose.
4. Read `window.gameState()` after each step and compare it with what
   the screen shows.
5. Report: what broke, how to reproduce it, console errors, screenshots.
   Don't fix anything in this skill.

The last line is deliberate. A playtest that also fixes things hides what it found, so keep finding and fixing in separate steps and read the report before you ask for fixes. window.gameState() is a small function your game exposes for tests; playtesting games with AI shows how to build it and how Claude drives the browser.

A balance-pass skill

A balance skill reads balance.json, runs the game’s simulation or tests with the current numbers, and proposes changes as a table (old value, new value, why) before touching the file. Put disable-model-invocation: true in its front matter if you want it to run only when you type /balance-pass (skills docs).

An add-content skill

“Add an enemy” is the same six steps every time: sprite or model, stats in the data file, spawn rule, one behavior, one test, one line in the changelog. Write the steps down once, and the tenth enemy arrives as tidy as the first.

Skills can carry files too, such as a references/ folder with your art style sheet or a scripts/ folder with a helper the skill runs. Inside the body, $ARGUMENTS holds what you typed after the command, so /add-enemy slime that splits in two reaches the skill as text (skills docs).

Hooks run your checks every time

A hook is a command Claude Code runs on an event such as PreToolUse, PostToolUse, Stop or SessionStart, configured in .claude/settings.json (hooks reference). Anthropic calls CLAUDE.md instructions advisory; hooks are deterministic and guarantee the action happens (best practices).

Anthropic’s own example formats every file Claude writes (hooks guide):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

Exit codes carry the meaning. Exit 2 from a PreToolUse hook blocks the call, and exit 2 from a Stop hook keeps Claude working. After a PostToolUse hook the edit has already happened, so exit 2 only shows your hook’s error output to Claude (hooks reference). Two game patterns follow from those rules:

• Protect built files. A PreToolUse hook on Edit|Write that exits 2 when the path starts with public/assets/ stops hand edits to generated art.
• Test before stopping. A Stop hook that runs your fast logic tests and exits 2 on a failure sends Claude back to fix them. Keep that test run under a few seconds, or every turn drags.

Try a new hook on a throwaway branch first, since a Stop hook that always fails keeps sending Claude back to work.

Subagents for a second opinion

A subagent is a Markdown file in .claude/agents/ whose body is its instructions, with name and description required and tools and model optional (subagents docs). Claude delegates to one when the description matches, or you call it by name with @agent-<name>.

Start with a read-only reviewer. Give it only Read, Grep and Glob in tools, and tell it to check a diff against CLAUDE.md and the spec. It never saw the conversation that produced the code, so it reads the diff cold. An asset auditor makes a good second one: file sizes, texture dimensions, unused files, missing credits.

Share the setup as a plugin

When the skills, hooks and agents work, bundle them. A plugin is a folder with .claude-plugin/plugin.json plus skills/, agents/ and hooks/hooks.json (plugins overview). Two public examples for games:

• Unity announced an official Claude Code plugin on September 9, 2026, with 29 skills (Unity blog). Install it with /plugin marketplace add Unity-Technologies/unity-agent-plugin, then /plugin install unity@unity-agent-plugin. It needs Unity 6 or later, also works in Codex, and its README warns that the skills edit scripts, scenes and assets directly, so commit first (repo).
• Claude Code Game Studios is an MIT-licensed collection with skills such as /playtest-report, /balance-check and /asset-audit for Godot 4, Unity and Unreal 5 (repo).

Read any skill before you install it. In February 2026 Snyk scanned 3,984 skills from the ClawHub and skills.sh registries and reported 13.4% with critical issues and 76 malicious payloads (Snyk). A skill is instructions plus scripts, and it runs with your permissions.

The format also travels. Codex reads skills from .agents/skills (Codex docs), Cursor from .cursor/skills and .agents/skills, and for compatibility from .claude/skills too (Cursor docs). Gemini CLI reads .gemini/skills or .agents/skills (Gemini CLI docs).

Tool	Project instructions	Skills folder
Claude Code	CLAUDE.md, or AGENTS.md when there is no CLAUDE.md	.claude/skills/
Codex	AGENTS.md	.agents/skills/
Cursor	.cursor/rules/*.mdc, AGENTS.md	.cursor/skills/, .agents/skills/, .claude/skills/
Gemini CLI	GEMINI.md	.gemini/skills/, .agents/skills/

Claude Code reads AGENTS.md on its own from version 2.1.277 when a repo has no CLAUDE.md (memory docs), so one instruction file can serve every agent.

A day with the setup

Start a session with a spec. Anthropic’s guide suggests letting Claude interview you and write SPEC.md first (best practices). Build one mechanic, let the Stop hook hold Claude to green tests, then run /playtest. Read the report, ask for fixes in a fresh message, and commit.

When a session wanders, /clear beats a third correction. /rewind restores code and conversation to an earlier prompt, but it doesn’t track changes made through shell commands and doesn’t replace git (checkpointing).

For scripted jobs, such as a nightly balance report, claude -p "prompt" runs without the interactive UI and can print JSON with --output-format json (headless docs).

Next: connect tools and playtest

• MCP servers for game development: connect Claude Code to a browser, Blender, Godot or Unity.
• Playtesting games with AI: the gameState() hook, browser automation and deterministic tests.
• Claude Code game development: the first-game version of this guide.
• Games made with it: the Claude Code hub, 169 games and counting.