Use when writing or maintaining a Game Design Document. Provides the full GDD template (sections 1-9 covering overview, mechanics, world, player flow, monetization, tech specs), the living-document workflow (inline review comments + decision tracking + open questions), and rules for what belongs vs. doesn't. Use when starting a GDD after concept is locked, expanding an existing GDD with a new system, or auditing a stale GDD before the next milestone.
How this skill is triggered — by the user, by Claude, or both
Slash command
/gamedev-toolkit-claude:game-design-documentThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A GDD is the single source of truth for what your game is — concept, mechanics, world, player flow, monetization, tech specs. It's also a **living document**: design evolves, reviewers leave comments, decisions get made then questioned then re-made.
A GDD is the single source of truth for what your game is — concept, mechanics, world, player flow, monetization, tech specs. It's also a living document: design evolves, reviewers leave comments, decisions get made then questioned then re-made.
This skill provides the template, the workflow for maintaining it as it evolves, and the rules for what belongs in a GDD vs. somewhere else.
game-design-brainstorm → ready to expand to full GDDSingle-file (recommended for solo / small team, <50 pages):
docs/GDD.md<!-- @reviewer: question -->)Multi-file (recommended for 5+ team, 50+ page GDD):
docs/gdd/00-overview.md, 01-mechanics.md, ... separate files per major sectiondocs/gdd/decisions.mddocs/gdd/questions.mddocs/gdd/README.mdFor ARPG / city-builder / mobile PvP scale projects, multi-file pays for itself by month 3. For game jam or small-scope project, single-file is fine.
Below: every section a GDD should have, in order, with what goes where and what does NOT.
From game-design-brainstorm output:
Anti-pattern: don't expand the pitch into prose. The pitch should fit on a sticky note. Detail goes into Section 3+.
For systems-heavy games (city-builders, RPGs without narrative campaign), this section can be 1 page focused on setting + tone. For story-driven games, this section can be 30+ pages with branching dialogue trees in a separate doc.
Anti-pattern: don't write the entire script here. Reference a separate docs/script/ directory for dialogue and detailed narrative.
This is where you describe every gameplay system in enough detail that an implementer can build it without designer follow-up.
For each mechanic, structure:
### [Mechanic name]
**Purpose**: What this mechanic adds to the loop. Why it exists.
**Player verbs**: What the player does (in/with this system).
**Inputs**: Resources, choices, time the player commits.
**Outputs**: Rewards, progression, state changes.
**Rules**: How it works step by step. Include numbers (cooldowns, damage formulas, costs).
**Failure / edge cases**: What happens when the player can't do this? Empty input? Conflicting inputs?
**Open questions**: <!-- @designer: question -->
**Cross-references**: Links to other systems this depends on (e.g. "depends on the Tech Tree from §3.4")
Common mechanics to cover for different genres:
City-builder / colony sim:
ARPG:
arpg-systems-checklistMobile PvP:
Roguelite:
Universal:
For open-world games, this becomes a sub-doc (docs/world/). For arena-based games (PvP), this is the maps reference.
The user-facing first 30 minutes + critical paths after.
Cover in order:
This section is the player retention contract. Get it right and players stay. Skim it and they bounce in 5 min.
For polished projects this expands into a separate Art Bible document. For prototypes, 2-3 pages is fine.
Skip this entire section if your game is pure paid (single purchase, no DLC). For F2P / live-service:
Be honest in this section. F2P that says "no pay-to-win" but ships hard pay-to-win loses trust fast.
A GDD is not "write once, freeze". Design evolves. The workflow:
When reviewing a section, leave comments rather than overwriting. Two formats:
HTML comment style (markdown-clean, invisible in rendered output):
The Player can build up to 80 buildings.
<!-- @marcin 2026-01-15: too many? Test 30, 50, 80 caps in prototype before committing -->
<!-- @collaborator 2026-01-16: agreed, 80 feels arbitrary. Add to open questions. -->
Visible comment style (for when comments themselves are content):
> **Open question (@marcin, 2026-01-15)**: should building count cap at 80 or scale with zone tier?
> **Reply (@collaborator, 2026-01-16)**: scale with tier — 30/50/80 by zone level. Forces tradeoff: rush new zone vs. consolidate.
Pick one style per project, stick with it.
Major design decisions go to docs/gdd/decisions.md (or a section in single-file GDD):
## Decision log
### 2026-01-15: Building count cap scales with zone tier
**Question**: hard cap at 80 or tiered?
**Options considered**: flat 80 cap; tiered (30/50/80); unlimited but resource-bottlenecked.
**Chosen**: tiered.
**Why**: forces explicit tradeoff between rushing new zones and consolidating existing colony. Flat cap is arbitrary; unlimited removes a design lever.
**Revisit if**: playtests show players don't engage with the rush-vs-consolidate choice.
Without this log, "why did we decide X" gets re-litigated every 3 months.
## Open questions
- [ ] Should colonists have a "sanity" stat in addition to happiness? (@marcin, 2026-01-15) — Defer to prototype, decide month 3.
- [ ] Tutorial: forced or skippable? (@collaborator, 2026-01-20) — Need playtest data.
- [ ] Save system: cloud-only or local + cloud? (@team, 2026-01-22) — Steam Cloud auto-syncs `persistentDataPath`, default to that. Confirm month 4.
Mark [x] and move to decision log once resolved.
When a system gets removed or replaced, don't delete it from the GDD — mark it deprecated with a date and a reference to what replaced it:
### Skill respec system (DEPRECATED 2026-02-10)
Originally: free respec at any time via menu.
Replaced by: respec items as rare drops (see §3.7 — Items).
Reason: free respec removed all build commitment. Items create scarcity decision.
This preserves design history for future "wait, didn't we try X already?" conversations.
tech_state.mdworking_memory.md or your project trackerdocs/script/If you find yourself adding sprint-level detail to the GDD, you're conflating documents. The GDD answers "what is this game"; other docs answer "how do we ship it" and "what's broken right now".
decisions.md — every major change goes into oral tradition, future-you forgets why.The Sea Nation GDD (city-builder / colony sim) covers:
The SimRoyale GDD (mobile PvP RPG) covers:
Different genres, same meta-structure. Use one as a template, swap the genre-specific mechanics.
npx claudepluginhub marcin-elj/gamedev-toolkit-claude --plugin gamedev-toolkit-claudeGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.