prototype skill

!bash "${CLAUDESKILLDIR}/../../hooks/yaml-helper.sh" resolveconfig --keys reviewmode,automation

Purpose

This is the concept prototype — a fast, throwaway build that answers one question: "Is this core idea actually fun to interact with?"

Default use — run right after /brainstorm and /setup-engine, before writing GDDs or architecture docs. Its verdict determines whether the concept is worth the investment of full design documentation.

Mid-production? You can also run this at any stage to test a specific mechanic, design change, or technical question. Pass --spike to activate spike mode: a lightweight ~4-hour build with no GDD prerequisites and no phase gate implications.

Already have GDDs and architecture complete? To validate the full game loop before committing to Production, run /vertical-slice instead.

Phase 1: Define the Question

Every AskUserQuestion call follows .claude/docs/automation-modes.md (collaborative asks always · guided major-only · autonomous logs and proceeds; automationalwaysask categories always prompt).

Check for spike mode: If --spike was passed, skip to the Spike Mode section at the bottom of this skill.

Otherwise, use AskUserQuestion to confirm intent before proceeding:

• Prompt: "How would you like to use this prototype session?"
• Options:
• Prototype this concept — build a throwaway build to validate the core idea is fun before writing GDDs (1–3 days)
• Skip — concept already proven — I have enough evidence this works; log it and proceed directly to design
• Mid-production spike — I'm already in Production and want to test a specific mechanic or technical question quickly (~4 hours, no phase gate implications)

If "Skip — concept already proven": Ask (plain text, not a widget): "What evidence do you have that the concept works?" Record the one-line answer, then stop. Note: "Concept prototype skipped — evidence: [answer]." Suggest next step: /map-systems or /design-system [mechanic].

If "Mid-production spike": skip to the Spike Mode section below.

If "Prototype this concept": continue with Phase 1 below.

A note on prototype strategy: The research on successful indie development is consistent — building 2-3 concept variants and letting the best one win is far more likely to succeed than iterating one concept until it works. This is your first prototype, not necessarily your only one. If this prototype produces a PIVOT verdict, consider whether to refine this concept OR start fresh with a different angle on the same game idea and prototype that instead.

Game jam as a prototype vehicle: If you're planning a concept prototype anyway, consider timing it to a game jam (Ludum Dare, GMTK Game Jam, Global Game Jam). Jams provide a forced timebox (48-72 hours), instant distribution to thousands of players who rate and review early builds, and a deadline that prevents scope creep by design. Many shipped games (Celeste, VVVVVV) began as jam prototypes. Not required — but worth considering if the timing is right.

Read the concept description from the argument. Before building anything, define the falsifiable hypothesis this prototype must answer:

"If the player [does X], they will feel [Y] — we will know this is true if [measurable signal Z]."

Good: "If the player swings on grapple hooks, traversal will feel fluid — we'll know if players chain 3+ swings without stopping within 2 minutes of picking it up."

Bad: "Does this feel fun?" ← not testable, not falsifiable.

If the concept is too vague to form a hypothesis, stop here. Ask the user to narrow the question before proceeding. A prototype without a clear question wastes time.

Also ask: "What is the riskiest assumption in this concept?" That is the first thing the prototype should test — not the easiest part, the riskiest.

Phase 2: Load Concept Context

Read design/gdd/game-concept.md if it exists. Extract:

• Core fantasy (what the player is supposed to feel)
• Core loop (the moment-to-moment action being tested)

Determine the engine and language in use: read engine.name and engine.language from project.yaml. For each field, if its key is absent or empty (including when project.yaml has no engine: block), fall back to CLAUDE.md and .claude/docs/technical-preferences.md. Treat a [TO BE CONFIGURED] value as not set.

Phase 3: Choose the Prototype Path

Select the prototype path. If --path [html|engine|paper] was passed, use that. Otherwise, use this quick-reference first, then read the full path details below:

Rule of thumb: "Does this feel right?" → Engine. "Are these rules interesting?" → Paper. "Is this logic correct?" → HTML or Paper.

Path: HTML (browser-playable)

Best for: Puzzle games, card games, turn-based strategy, word games, idle games, top-down logic games. Anything where timing precision doesn't matter.

Reliability: ~85–90% one-shot. The agent writes a single self-contained HTML file the user opens in a browser — no install required.

Limitation — browser latency lies about game feel. Browsers introduce 50–133ms of rendering variance. This makes HTML prototypes fundamentally unreliable for action games, platformers, fighting games, or anything where input timing, jump arcs, or collision feel are what you're testing. If feel is the hypothesis, use the Engine path instead.

Alternative tools for this path: PICO-8 (extreme constraints, great for retro arcade concepts, web-export in one command), Phaser.js (more capable browser game framework, still no install needed), or Twine (narrative/choice-based games). These are faster than raw HTML for their respective genres — suggest them if appropriate.

Output: A single prototype.html (or PICO-8/Phaser equivalent) the user opens in any browser.

Distribution — the HTML path's biggest advantage: Unlike Engine prototypes, this build can reach real players globally in minutes. Use this actively:

within hours. Free. The indie community plays rough builds here without expecting polish. This is genuine external validation at zero cost.

• itch.io — upload the file, share the link, get play counts and written feedback

screen + audio with Loom while playing. You get a video of real first-impression reactions and confusion without synchronous scheduling.

• Loom + file share — share via Google Drive/Dropbox, ask someone to record their

test early builds and give unsolicited honest feedback.

• r/playmygame or r/WebGames (Reddit) — active communities that specifically

other's prototypes routinely; an HTML file is the easiest possible ask.

• Game dev Discord servers (GMTK, Brackeys, GameDev.tv) — members test each

Path: Engine (engine project)

Best for: Action games, platformers, physics-heavy games, anything where moment-to-moment feel IS the hypothesis. Use this when HTML latency would lie about the result.

Reliability: ~50–60% one-shot. Expect 2–4 rounds of iteration — this is normal, not a failure.

Limitation — requires engine installed and running. This path is a multi-turn collaborative loop:

1. Agent writes the code
2. User runs it in the engine
3. User reports errors or observations
4. Agent fixes and iterates

Sunk cost rule: If the user has been iterating for more than 2 hours without reaching a playable state, stop. The scope is too large or the question is wrong. Reframe the hypothesis and simplify aggressively, or switch to Paper path.

Output: A minimal runnable engine project in prototypes/[name]-concept/.

Lighter alternative — Love2D (Lua): If the project engine (Godot, Unity, Unreal) feels too heavy to stand up for a throwaway build, consider Love2D — a minimal 2D framework that installs in minutes, requires no project scaffolding, and renders natively with no browser latency. Used by many indie devs for rapid 2D action and platformer prototypes (Balatro prototyped in Love2D; Nuclear Throne's early builds used it). It sits between HTML overhead and full engine overhead: heavier than opening a browser, lighter than setting up a full engine project. Best for 2D action/platformer feel validation when the project engine is 3D-first or takes significant time to configure.

Path: Paper (rules document + play log)

Best for: Strategy games, card games, board game-style mechanics, economy systems, progression loops, any game where the logic can be simulated by hand. Works for any genre when you need to validate rules, not feel.

Reliability: 100%. No code, no engine, no install.

Limitation — cannot validate moment-to-moment feel. Paper prototypes prove that the rules are internally consistent and the decisions are interesting. They cannot tell you whether jumping feels right or whether explosions feel satisfying.

Paper playtest observation protocol (run this with 5+ people):

1. Brief the rules once. Hand them the rule summary sheet. Then step back.
2. Do NOT explain further. Do NOT help. Do NOT clarify. Confusion is data.
3. Watch silently. Note every moment they slow down, re-read, or ask a question.
4. After the session, ask one question only: "What was confusing?" — not "Did you like it?"
5. Use fresh testers for each iteration. The same person cannot give new first-impression data.
6. If 3+ testers hit the same confusion point, that rule is broken — redesign it before re-testing.

Output: A printable rules document + a completed play log showing one simulated session.

Narrative tools for this path: For dialogue-heavy and story-driven games, skip the generic rules doc — use a dedicated narrative scripting tool instead: