agentleFS
Sign inStart free
JoaoEquerJoaoEquer/Oficina/skills/game-design-doc/SKILL.md

game-design-doc

Skill2 starsChanged 25 days agoMITView on GitHub

Builds or reviews a Game Design Document (GDD) for a game project - core loop, pillars, progression, economy formulas, UI, MVP scope and out-of-scope - by reading the project first and interviewing the owner with the grilling skill, writing only confirmed decisions. Has a review mode that compares an existing game's code against its GDD and lists the gaps, and a reference for idle/incremental economy math. Use whenever the user wants a GDD, game design doc, "documento de design", game pitch, roadmap of mechanics, asks "how do I improve this game", "is the progression balanced", "what is missing in my game", or starts a new game project (Unity, Electron, Roblox, any engine). EXPERIMENTAL - only load in game projects.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use the grilling skill: rounds of numbered questions, each with your recommended answer.

    line 25
  2. Very specific:

    Keep it under ~250 lines. Longer = split into docs/design/.

    line 38
  3. Very specific:

    Run references/review-checklist.md against code + GDD.

    line 41
  4. Distinctive:

    Do not run balance simulations unless the owner asks.

    line 48
  5. Distinctive:

    Do not edit game code in this skill.

    line 49
  6. Distinctive:

    Do not invent tone, theme, monetization or platform.

    line 50

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Game design doc

Provenance: own skill (2026-10-22), experimental. Not yet repeated in two real projects (see Validation). Interview method delegates to grilling; structure follows the pillars/loop/scope shape already used by a real project's docs/roadmap.md and CONTEXT.md.

A GDD here is a decision record, not a wish list. Every line is either CONFIRMED (the owner said it or the code proves it) or PENDENTE (open). Never fill a section with plausible-sounding design the owner did not choose.

Modes

  • Build (no GDD yet): read the project, interview, write GDD.md.
  • Review (GDD or code exists): compare, list gaps, propose next increments. Does not rewrite decisions.

Pick the mode from the project: GDD.md present or substantial docs//code present = Review first; empty project = Build.

Process

1. Read before asking

Facts are your job, decisions are the owner's. Read: README, AGENTS.md, CONTEXT.md, docs/ (roadmap, ADRs, design notes), package.json/project settings (engine), the game-rules source (content tables, formulas, constants), tests. Note what already answers each GDD section. Never ask something a file answers.

2. Interview (Build) or gap list (Review)

Use the grilling skill: rounds of numbered questions, each with your recommended answer; only ask the frontier. Order of the design tree:

  1. Pillars (3-7) and the one-sentence fantasy. Everything below must serve a pillar.
  2. Core loop (what the player does in the first 30 seconds, 5 minutes, one session).
  3. Progression and economy (see references/idle-economy.md for idle/incremental games).
  4. Content plan (what exists, what is the minimum for a playable MVP).
  5. UI/UX and first-session flow.
  6. Target platform, session length, monetization (or "none").
  7. Scope: MVP list and an explicit out of scope list.

3. Write GDD.md from templates/GDD.md

  • Language: the project's (a PT-BR project gets a PT-BR GDD).
  • Numbers come from code or the owner. If a formula is in code, cite file:symbol instead of copying values that will rot.
  • Link, don't duplicate: art style and asset naming live in ASSETS.md (game-assets skill); glossary in CONTEXT.md (domain-modeling); big decisions in ADRs.
  • Keep it under ~250 lines. Longer = split into docs/design/.

4. Review mode output

Run references/review-checklist.md against code + GDD. Report, ranked:

  • Gaps: GDD says X, code does Y or nothing (file:line).
  • Risks: broken economy, dead choices, no first-session hook, scope creep.
  • Next increments: small, testable, each tied to a pillar. Not "rebalance everything". Be honest about what is unverified: a balance claim without a run/test is an opinion, label it.

Rules

  • Do not run balance simulations unless the owner asks; they burn plan limits. Read existing probes/tests and quote their results instead.
  • Do not edit game code in this skill; GDD and review only.
  • Do not invent tone, theme, monetization or platform; ask or mark PENDENTE.
  • A game with no "out of scope" list has no scope. Insist on it.

Validation (experimental)

Record each real project where this skill was used, and what it changed. Promote to stable after two.

ProjectDateModeResult / what was missing
Galaslime (idle-game)2026-10-23ReviewGDD sem entrevista, 21 itens do checklist: MVP numérico, fora de escopo e gancho de retorno ausentes; escolhas mortas e duração da luta não verificadas sem rodar sonda. Review não fechou sozinho: falta o dono responder os PENDENTE.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free