Skip to main content
skill CX Codex

game-docs — Claude Code skill: what it does, how to install

game-docs — a skill for Claude Code and Cursor writes and maintains game design documentation synced with the codebase.

Apache-2.0 2,000 installs ★ 10,033 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill game-docs -a claude-code
Open on GitHub

What game-docs does

The agent maintains a single-page GDD featuring a feature index alongside concise design notes, matching numbers against the repository code. A built-in Python script validates links and statuses within the project documentation folder. Running the validation script requires Python installed on the system.

Documentation adapts to playtests and code changes while preserving the existing project structure. Supported workflows range from drafting initial specs to recording design choices and syncing feature statuses across revisions.

playtest tuning or code edits.

What it helps with

  • draft a new game design document from scratch
  • update feature specifications after playtests
  • verify link and status consistency in design files
  • record a design decision for a specific mechanic

Example prompts for the agent

  • Draft a GDD for our new platformer game
  • Spec out the dash mechanic for the player
  • Update docs to match the inventory system code changes

How to install game-docs

1Skills CLI (Vercel)

npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill game-docs -a claude-code

2Manually: put the files in place

~/.claude/skills/game-docs/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/game-docs/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about game-docs

How to install game-docs in Claude Code?

Run npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill game-docs -a claude-code and check ~/.claude/skills/game-docs/SKILL.md.

What does game-docs do?

It creates and updates game design documents, links them directly to code implementations, and runs status checks on features.

What is needed to run game-docs?

Python is required to execute the documentation validation script.

Source text

SKILL.md · Apache-2.0
---
name: game-docs
description: >
  Writes and maintains a game's design docs: a one-page GDD with a feature index and short feature
  notes, kept true to the code by a link and status checker. Use for "draft a GDD", "spec out this
  mechanic", or updating docs after a playtest or code change. Not for building a game when no
  docs were asked for (`prototype-fast`, `game-jam`), READMEs or level layouts (`level-design`).
---

# Game docs

Keep a game's design written down in as few words as will stay true. The GDD is one page that says what the game is and maps its features; each feature's detail lives in its own short note; and every number in the docs matches the code. Docs nobody keeps current are worse than none, so write less, edit in place, and sync after every change.

## When to use

Run only when the user asked for game design docs, or when the project already has a GDD and a feature is being designed, changed, built or cut. A request to build a game or a feature is not a request for docs: let the engine and genre skills build it (through `$router`) and offer docs in one line at the end. Level layouts go to `$level-design`; READMEs, API docs and code comments are not this skill's job.

## Workflow

1. **Look before writing.**
   - Find the existing docs: `GDD.md`, `*design*`, `*spec*`, `docs/`, `design/`, a wiki folder, `specs/` (GitHub spec-kit) or `.kiro/specs/` (Kiro). Keep their folder, file names, language and format.
   - Read the conversation (a planning chat is your main source) and, when code exists, the repo and `git diff`/`git log`. Never ask what the repo or the chat already answers.
   - Sort the project into one of three cases. This decides everything below:
     - **No GDD.** Only a request for a GDD starts one.
     - **A GDD in this layout** (a feature index plus `features/<slug>/design.md`). Use the modes as written.
     - **A GDD in any other form** (one long file, a wiki page, spec-tool folders). **Edit it in place, in its own format.** Make the smallest edit, in the user's style. Don't add an index, folders or headers to it, and don't suggest restructuring unless the user asks (mode E).
2. **Pick the mode** and read its section in [references/workflow-modes.md](references/workflow-modes.md):

   | The user wants | Mode |
   |---|---|
   | a GDD, and there is none | **A. Draft the GDD** |
   | a new feature written up | **B. New feature** |
   | a feature changed after a playtest, tuning, rework or cut | **C. Change a feature** |
   | the docs to match code that was just written or changed | **D. Sync after coding** |
   | an existing GDD split into this layout (asked for explicitly) | **E. Migrate** |
   | a design decision recorded | **F. Record a decision** (also inside every other mode) |

3. **Write.** Use the template for the doc you are creating and [references/doc-rules.md](references/doc-rules.md) for where each fact lives, decision rows and proof annotations. Change existing docs with small edits to the affected section; don't regenerate a whole doc, because the user's own wording is part of the design.
4. **Verify.** Run the checker on the docs folder (paths are relative to this skill's folder; use `python` where `python3` doesn't exist):
   ```bash
   python3 scripts/check_docs.py <project>/docs
   python3 scripts/check_docs.py <project>/design --gdd game-design.md   # GDD under another name
   ```
   Exit 0: no errors. Exit 1: fix each `ERROR`, and each `WARNING` that is real; say why the others don't apply. Exit 2: wrong folder or `--gdd` name. A `NOTE gdd-no-index` means the GDD is not in this layout; that is fine, so leave its structure alone. Then reread every number you touched against its source (the code, the diff or the user's message).
5. **Hand off** in a few lines: the docs created or changed (as links, or the diff for a small edit), the substance in 2 to 4 lines, the `[ASSUMPTION]`s and the questions that really matter, and decisions logged or statuses changed. Add a next step only if it isn't obvious. No to-dos or offers of more docs unless the user asked. Don't commit unless asked.

## What to write, and when

| Moment | Write |
|---|---|
| The user asks for a GDD | `GDD.md` from the template, about one page, with the real design in it, plus a `design.md` with a concrete first proposal (rules and starting numbers, `[ASSUMPTION]`-marked) for the 2 or 3 features the core loop needs. Other features are index rows with status `idea` |
| A feature is designed | its `features/<slug>/design.md` |
| A feature first gets code (status `in progress`) | its `implementation.md` and `testing.md`, short, written against the real code |
| Code that several features share appears (save format, event bus, scene flow) | `ARCHITECTURE.md`. Until then, one line in the GDD summary names the engine |

Write more only when the user asks for it. A plan for code that doesn't exist yet goes stale before the engine is chosen, so it is not written by default.

**Statuses**, the same words everywhere: `idea` → `designed` → `in progress` (code has started) → `implemented`, plus `changed — code pending` and `cut`. A feature's status lives in two places, the GDD index and `design.md`'s `**Status:**` header, and they must agree.

**Questions.** Ask at most one short round before the first draft, and none when the user said "just draft it" or already gave the answers. Ask only what you must not guess: the core fantasy (what the player does and feels), the audience and the platform, plus anything that blocks the draft. Number the questions, give each 2 to 4 options with your recommendation first, and say shorthand answers are fine ("1b, 2: PC only"). Fill every other gap with a sensible default marked `[ASSUMPTION]` and list the open questions in the handoff, where answering them costs the user nothing.

## Gotchas

- **"Draft a GDD" produced 20+ files.** Writing a design note, an implementation plan and a test plan for every MVP feature, plus an ARCHITECTURE.md, before any code exists. Follow the table above: one GDD page plus notes for the core-loop features only.
- **The GDD came back as an empty template.** Pillars and a feature list with every rule deferred give the user nothing to build or argue with. Propose the core mechanics with starting numbers, mark them `[ASSUMPTION]`, and let the user change them.
- **Unasked extras in the user's doc or reply.** To-dos written into their GDD, offers to restructure, "want me to write more docs?" lines. Edit what was asked; put real open questions in the reply.
- **A plain GDD got restructured.** The user asked to "update the dash in our GDD" and the agent added a feature index or folders, often to clear checker messages. Edit the GDD where it is; the checker's `gdd-no-index` is only a note.
- **"Record this decision" started a doc set.** With no GDD, add the decision where the project keeps notes; mode F says where.
- **Asking for numbers that are already in the code.** Playtest tuning often lands in code before the docs. In modes C and D, read the diff first, and set `changed — code pending` only when the code really lacks the change.
- **The agent stalls on questions.** Three rounds of interview, or a "where should the docs go?" stop. Use `docs/` (or the existing folder), name it in the handoff, and ask one round at most.
- **A ticked criterion the test doesn't prove.** The test's name was trusted, not its assertions. Read the test body and tick only the proven part ([proof annotations](references/doc-rules.md#proof-annotations)).
- **Two docs disagree on a number.** It was copied. Each fact has one home; everything else links to it.
- **Feature docs beside a spec tool.** If the project uses spec-kit (`specs/NNN-name/spec.md`) or Kiro specs (`.kiro/specs/<name>/`), those are the feature docs. Link them from the GDD index instead of writing `features/` copies.
- **Links break after a rename.** Slugs never change once created; rename the feature's title, not its folder.
- **Content vanishes in a migration.** Mode E moves text close to verbatim and checks with `--old <copy> --max-issues 0`, so no reported line is hidden.

## Resources

- [references/workflow-modes.md](references/workflow-modes.md): the steps for modes A to F. Read only the section for the chosen mode.
- [references/doc-rules.md](references/doc-rules.md): one fact, one home; what counts as a feature; decision rows; proof annotations; testing pitfalls; writing rules. Read before writing or syncing any doc.
- [references/gdd-template.md](references/gdd-template.md): read when drafting a GDD (mode A) or migrating one (mode E).
- [references/feature-templates.md](references/feature-templates.md): read when creating a feature's `design.md`, `implementation.md` or `testing.md`.
- [references/architecture-template.md](references/architecture-template.md): read when shared code first needs an ARCHITECTURE.md.
- `scripts/check_docs.py`: read-only checker (workflow step 4). `--help` lists its options and every issue code.

## Related skills

- `$router`: picks the engine and genre skills that build what the docs describe.
- `$prototype-fast`: finding out whether a mechanic is fun; write its feature note once it is kept.
- `$game-jam`: scoping under a deadline. Jam docs are the GDD page and nothing else.
- `$level-design`: layouts, pacing and encounters for individual levels.

© gamedev-skills · Apache-2.0 · gamedev-skills/awesome-gamedev-agent-skills

Similar skills

All skills for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set91

The whole set →
roblox-studio-workflow roblox-studio-workflow — a skill for Claude Code and Codex guides edits across Roblox places and Rojo projects. Activates when editing .rbxl files, working with Studio MCP tools, or verifying changes. CX Codex +1 9,300installs roblox-physics Claude Code skill for Roblox physics and spatial queries, managing assemblies, constraints, and network ownership. CX Codex +1 9,100installs ebitengine-game ebitengine-game — a skill for Claude Code that creates, debugs, and packages 2D games in Go using Ebitengine v2. CX Codex +1 6,000installs defold-core defold-core — a skill for Claude Code, Codex, and Cursor that builds and debugs Defold 1.14 Lua games. Runs when editing .collection or .script files. CX Codex +1 5,800installs unity-build-size unity-build-size — a skill for Claude Code analyzes build reports, spots oversized textures, audio and glTFast models in Unity 6.3 LTS projects, and shrinks build size. CX Codex +1 1,800installs roblox-simulator-economy roblox-simulator-economy — a skill for Claude Code designs upgrade cost curves, passive income rates, rebirth pacing, and offline gains for Roblox idle games in Luau. Runs during balance tuning for simulators and tycoons. CX Codex +1 ★ 10,033repo stars workflows workflows — a Claude Code plugin that brings game development process skills: game jam runs, rapid prototyping, Steam and itch.io publishing. It covers the shipping cycle from first prototype to store page. ★ 10,033repo stars genres A Claude Code plugin with compositional templates for nine game genres: platformer, roguelike, RPG, FPS, tower defense, card game, visual novel, survival, puzzle. Sets project structure and core mechanics for the chosen genre. ★ 10,033repo stars

Project sponsors

Companies that keep this analytics open