board-game-design

---

🤔 Why

You sketch a board game. The agent suggests ten mechanisms. Next session it forgets your locked decisions and redesigns from scratch.

The usual workarounds do not help:

• "Design me a worker placement game" → generic mechanism dump, no project files
• "My game feels boring" → three unrelated rule changes, no diagnosis
• "Balance these cards" → numbers without playtest evidence or a falsifiable hypothesis

Board Game Design turns tabletop iteration into a structured agent workflow — design state, symptom routing, single-variable experiments, and paper PnP templates your agent maintains across sessions.

Compatible with any host that loads the open Agent Skills standard — Claude Code, Codex, Cursor, and others read the same SKILL.md format.

Agent instructions live in SKILL.md and progressive-disclosure companions — per Anthropic skill authoring guidance.

Guideline: Build your own board game

---

📦 What you get

Path	Role
SKILL.md	Entrypoint: modes, invariants, indexes, default outputs
templates/design-state.md	Single source of truth — Locked, Claims, Evidence, Kill overrides
genre-profile/	Euro, party, social-deduction, solo, coop design lenses
routing/symptom-index.md	Symptom → diagnostic routing ontology
routing/context-budget.md	Per-mode context budget (required / optional / forbidden)
reasoning/	Design reasoning, decision matrix, hypothesis rules, experiment priority
diagnostics/	System (BG*) + experience (ED001–ED008) guides
experiments/	Experiment framework
kill-criteria.md	Continue / Restructure / Pause-or-Kill gate + parameterizable thresholds
lint/	Design lint BG001–BG020 + Design Confidence Model
prototype/	Fidelity ladder, selection matrix, optional-runtime boundary
runtime/	Optional Python companion (bgd-sim) — Monte Carlo, population, P2 CLI
balance/	Balance model, value budget with Effective Value Range
theme-and-experience.md	MDA depth, Target Player Model, theme-mechanism fit, emotion curve
tools/	Export pipeline, component schema, nanDECK, TTS, digital-assets catalog
skills/	Standalone companion skills (bgd-*) — auto-loadable by Agent Skills hosts
chapters/	13 mechanism distillations (Building Blocks categories)
patterns.md	High-leverage mechanism patterns
cheatsheet.md	Decision rules + symptom routing + mixed-demand priority
workflow.md	Milestones 0–5 with regression allowed
playtesting.md	Five playtest frameworks + experiment tie-in
probability-and-balance.md	Failure modes, McDie, dice intuition
templates/	Project copy-out files (incl. simulation-run.md)
templates/examples/micro-scavenger/	Format reference example game
eval/	Benchmarks, validators, golden/ schemas
eval/benchmark-prompts.md	Behavior evaluation cases (Create through Fidelity)
eval/README.md	Structural + behavior eval workflow
CHANGELOG.md	Semver release history

Chapter files load on demand — agents should read the smallest file that answers the question, not all chapters at once.

Default outputs are project files, not prose-only advice. Format reference: templates/examples/micro-scavenger/. Choose the cheapest valid fidelity for the hypothesis; paper PnP remains the usual P4 human-playable build.

---

⚙️ How it works

Core loop

Intent → Claim / Hypothesis → Select minimum valid fidelity → Prototype → Experiment → Evidence → Diagnosis → Decision → (update design-state) → repeat

Shorthand: concept → mechanism skeleton → cheapest valid prototype (sim / digital / paper) → playtest / balance → (optional) POD

Agent modes

Pick one mode per session. Load the smallest file set that mode requires.

Mode	Trigger	Load first
Create	New game from scratch	genre-profile/ (one) + workflow.md, theme-and-experience.md
Diagnose	Symptom (boring, broken, unfair)	routing/symptom-index.md → cheatsheet.md → diagnostics/*
Experiment	Test a specific hypothesis	experiments/framework.md + prototype/selection.md
Simulate	System question (balance, win rate, length)	prototype/fidelity-ladder.md, selection.md, runtime.md
Balance	Numbers, cards, economy	balance/README.md
Prototype	Build at chosen fidelity (often PnP)	prototype/selection.md → then P4 templates / tools

Hard invariants

1. Read design-state first — do not reopen Locked decisions without new contradicting evidence
2. Diagnose before changing — symptom + causal hypothesis before any rule change
3. Minimal intervention — one variable per experiment; no stacked fixes
4. Cheapest valid test first — do not over-build fidelity
5. System evidence ≠ experience evidence — sims do not prove fun; digital ≠ physical when required
6. Never auto-fix from a simulation anomaly

1. Evidence over opinion — playtest logs, SIM IDs, and experiment IDs, not "should feel better"
2. State preservation — design-state.md survives across chat sessions
3. Progressive disclosure — metadata → SKILL.md → one companion or chapter
4. Cheapest valid fidelity — P1 for system questions when modeled; P4 paper for table experience
5. Synthesized knowledge — mechanism trade-offs from Building Blocks, not raw book dumps
6. Automation validates systems; humans validate experiences

Core features

• Design state across sessions — Locked decisions, Claims, Evidence, Kill overrides, and Target Player Model in one project file
• Six focused modes — Create · Diagnose · Experiment · Simulate · Balance · Prototype; load only what the mode needs (routing/context-budget.md)
• Genre + mechanism knowledge — euro / party / social-deduction / solo / coop profiles; 13 Building Blocks chapter distillations on demand
• Dual diagnostics — system (BG*) and experience (ED001–ED008); symptom → diagnostic routing before any rule change
• Fidelity-aware prototyping — P0–P5 ladder; cheapest valid test; evidence types (simulation / digital / physical / expert)
• Simulate without requiring code — seeded simulation-run artifacts; optional runtime/ (bgd-sim) for population Monte Carlo, regress, and P2 CLI
• Balance + ship — Effective Value Range, PnP export pipeline, structural validators and behavior eval cases
• Digital assets — tools/digital-assets.md Quick pick for CC0 art, icons, fonts, SFX, and browser tabletops (Screentop / TTS)
• Standalone companion skills — skills/bgd-* (create, diagnose, assets, …) with their own description so Cursor / Codex / Claude Code can auto-load them independently of the hub

---

📥 Install

Copy or clone this repo into the skills directory your host scans.

Folder name must match the skill name: board-game-design.

Root SKILL.md must include YAML name + description.

Prefer trusted sources; skim bundled files before use. See agentskills.io/specification.

Hosts that recursively discover **/SKILL.md will register the hub and companion skills under skills/ (bgd-create, bgd-assets, …) so each can auto-load independently. If a host only loads the package root, use the hub — it routes to the same files.

Claude Code

~/.claude/skills/board-game-design/          # user-wide
<project>/.claude/skills/board-game-design/  # project-scoped (preferred when sharing a game repo)

git clone [email protected]:kyle-ip/board-game-design.git ~/.claude/skills/board-game-design

Codex

~/.agents/skills/board-game-design/          # user-wide
<project>/.agents/skills/board-game-design/  # project-scoped

Vercel skills CLI (symlinks into Codex's skills directory):

npx skills add kyle-ip/board-game-design -a codex
# or:
npx skills add https://github.com/kyle-ip/board-game-design -a codex

git clone:

git clone [email protected]:kyle-ip/board-game-design.git ~/.agents/skills/board-game-design

inside Codex: $skill-installer with this repo's URL.

Codex detects new skills automatically; restart if one does not appear.

Cursor

~/.cursor/skills/board-game-design/          # user-wide
<project>/.cursor/skills/board-game-design/  # project-scoped (preferred when sharing a game repo)

git clone [email protected]:kyle-ip/board-game-design.git ~/.cursor/skills/board-game-design

(Optional) simulation companion

Not required for design modes. For executable Micro-Scavenger Monte Carlo / population / regress / P2 CLI:

pip install -e ./runtime
bgd-sim run --game micro-scavenger --runs 1000 --seed 42 --population mixed --out sim.json

See runtime/README.md and prototype/runtime.md.

---

🚀 Usage

Good prompts give the agent mode, constraints, and artifacts (or paths).

Include	Why
Player count, time, audience	Stops generic mechanism dumps
Target feel (tension, bluff, puzzle, …)	Drives MDA-first design
Project path or @design-state.md	Agent reads Locked/Open/Rejected first
Observed symptom + evidence	Triggers Diagnose mode
One variable to test	Triggers Experiment mode
Output ask ("write files to ./my-game/")	Gets templates, not prose-only

Project-scoped tip: on session 2+, start with "Read design-state first, then …"

When it triggers

• Design or iterate a board / card game
• Choose or balance mechanisms (turn order, auctions, worker placement, cards, …)
• Diagnose problems (boring, unfair, snowball, etc.)
• Run playtest experiments with falsifiable hypotheses
• Rank which experiment to run next
• Evaluate continue / kill after 3+ playtests
• Build a print-and-play prototype
• Recommend free / CC0 art or digital tabletop assets

Companion skills (standalone)

Each major capability is also a separate Agent Skill under skills/. Hosts that discover nested SKILL.md files can auto-invoke them from natural language — no slash syntax required. (Some UIs may still list them as /bgd-*; that is optional.)

Skill	Does
bgd-create	Create mode — concept, design-state, mechanism skeleton
bgd-diagnose	Diagnose mode — symptom → BG*/ED*
bgd-experiment	Single-variable playtest experiment
bgd-simulate	System simulation artifacts
bgd-balance	Numbers / economy / EVR
bgd-prototype	Fidelity-selected prototype build
bgd-assets	Free art / icons / fonts / digital tabletops
bgd-export · bgd-tts · bgd-lint · bgd-kill	Export, TTS, lint, continue/kill gate
bgd-genre · bgd-playtest · bgd-print · bgd-workflow	Genre, playtest, print, milestones
bgd-cheatsheet · bgd-glossary · bgd-resources	Cheatsheet, terms, external links

Hub: board-game-design. Full index: skills/README.md.

Need CC0 meeple and dice icons for a Screentop prototype; commercial use OK — recommend a few sources

Design a 2–4p, 30 min coop about scavenging; target feel: tension + discovery; write files to ./micro-scavenger/

Compare mechanisms, write concept + skeleton + design-state. Ask for 2–4 candidates before locking rules.

Design a 2–4 player, 45-minute medium-weight game about Mars colony logistics.
Target feel: scarcity tension, long-term planning, light direct conflict.
Audience: hobby gamers who know Wingspan but not heavy euros.
Compare worker placement vs action drafting vs open market — recommend one with trade-offs.
Write concept-brief, design-state, and mechanism-skeleton to ./mars-habitat/ using the micro-scavenger example as format reference.
Do not write full rules yet.

I want a family co-op card game (2–4p, 20 min) with a Cthulhu investigation theme.
Core experience: dread + teamwork, not alpha-player quarterbacking.
Start with theme-and-experience (emotion curve), then suggest mechanisms that fit.
Output files to ./deep-shallows/.

Weak	Strong
"Make me a worker placement game"	Add players, time, feel, audience, and "compare 2–3 chassis before choosing"
"Design a card game about pirates"	Add "2p, 15 min, gateway, tension from hand limits" + output directory

Name the symptom, give playtest facts, ask for diagnosis + minimal experiment.

We've playtested 4 times (logs in ./orbital-mining/playtests/). Leader is usually decided by round 3; trailing players say they can't catch up.
Read design-state first. Diagnose (snowball vs low agency vs endgame drag), propose one falsifiable hypothesis, and draft EXP-005 — don't change three rules at once.

After 3 sessions, seat 1 wins 5/7 games at 4 players. Hypothesis: first pick on the worker track is too strong.
Run first-player-advantage diagnostic. Suggest the smallest rule change to test next, with success criteria (e.g. seat 1 win rate < 35% over 10 plays).

Specify baseline, variant, and measurable success.

Set up EXP-002: test hand limit 3 → 2 only. Everything else stays v0.6.
Hypothesis: smaller hand increases discard-pile fights without adding AP.
Success: in 4/5 playtests, both players contest discard at least twice; fun ≥ 3.5/5.
Write experiment.md and a blank playtest-log template for the next session.

Three hypotheses are open in design-state (HYP-001 through HYP-003). Read design-state first, rank them with experiment-priority, update the Experiment Backlog, and draft EXP-004 for rank 1 only.

Balance

Review CARD-014 through CARD-022 in ./deck-builder/components-sheet.md.
Build balance-spreadsheet rows using value-budget; flag any card where cost vs total estimated value differs by >40%.
State confidence, calibration source, use scope, and interaction/combo/timing dependency for each estimate.

Prototype

Turn ./v0.5/mechanism-skeleton.md into a paper PnP: rulebook-draft, components-sheet, pnp-checklist.
2–4p, 30 min, index-card prototype — no art. Export cards.csv per tools/export-pipeline.md if batch cards needed. Run lint/checklist before finishing.

Digital assets

Recommend 3 CC0 sources for card icons and wood-table textures for TTS; note attribution if any

Continue, restructure, or kill

We've completed PT-001 through PT-004. Core loop is learnable but average fun was 2.8/5 twice in a row.
Run kill-criteria.md with me: Continue, Restructure, or Pause/Kill? Cite evidence.

Mechanism lookup

Explain WPL-03 vs soft blocking (bumping) for a 2p game — trade-offs only, no new project files.

Mixed requests — diagnose/balance before prototype if something is broken.

• Players / time / audience / target feel
• New project vs continuing (read design-state first)
• Desired outputs (which templates, which folder)
• For iteration: symptom + evidence, not "make it better"
• For tests: one variable + success metric
• Optional: @file references to your repo artifacts

---

📁 Repository structure

board-game-design/
├── assets/
│   ├── fonts/                              # Fredoka (OFL) for banner typography
│   ├── logo.svg / logo.png                 # Loop Hex icon (minimal, no text)
│   ├── banner.svg / banner.png             # README cover (mark + title)
│   └── banner-square.svg / banner-square.png  # square mark banner (social / avatar)
├── SKILL.md
├── CHANGELOG.md
├── README.md
├── kill-criteria.md
├── theme-and-experience.md
├── workflow.md
├── cheatsheet.md
├── playtesting.md
├── probability-and-balance.md
├── genre-profile/                # euro, party, social-deduction, solo, coop
├── prototype/                    # fidelity ladder, selection, runtime boundary
├── runtime/                      # optional bgd-sim companion (Python)
├── routing/
│   ├── symptom-index.md
│   └── context-budget.md
├── reasoning/
├── diagnostics/
├── experiments/
├── balance/
├── lint/
├── tools/
│   ├── digital-assets.md         # free/CC0 art, icons, fonts, digital tabletops
│   ├── export-pipeline.md
│   ├── TTS-guide.md
│   ├── nanDECK-guide.md
│   ├── component-schema.json
│   └── examples/                 # cards.csv, cards.json, cards.nde
├── skills/                       # standalone companion skills (bgd-*)
│   ├── README.md
│   ├── bgd-create/
│   ├── bgd-assets/
│   └── …                         # see skills/README.md
├── eval/
│   ├── benchmark-prompts.md
│   ├── README.md
│   ├── validators/               # validate.py + validate_components.py
│   ├── golden/
│   └── fixtures/
├── chapters/                     # ch01–ch13
├── templates/
│   └── examples/micro-scavenger/
├── references/
└── …

---

🤝 Contributing

• Keep SKILL.md lean (<500 lines); put deep material in companions
• Prefer decision rules, state, and experiments over encyclopedic mechanism dumps
• Update CHANGELOG.md on each release
• Before minor/major releases: run Cases A–J per eval/README.md (≥6/8 behavior, G or J required); python eval/validators/validate.py --fixture-all must pass; optionally validate_components.py tools/examples/cards.json

---

License

Code and original skill text in this repository are released under the MIT License.

Links

• Agent Skills specification
• Anthropic: Equipping agents with Agent Skills