Design System
Walk through collaborative, section-by-section GDD authoring for one named game system with gates, dependencies, and incremental writes to your design folder.
Overview
Design-system is an agent skill most often used in Build (also Validate scope, Ship launch prep) that guides section-by-section GDD authoring for one game system with review gates and incremental doc writes.
Install
npx skills add https://github.com/donchitos/claude-code-game-studios --skill design-systemWhat is this skill?
- Section-by-section guided GDD authoring for a single system with incremental file writes
- Resolves review mode from CLI (--review full|lean|solo) or production/review-mode.txt
- Pulls context via Read/Glob/Grep and uses AskUserQuestion when system name is omitted
- Integrates director gates and systems-index.md priority when picking the next system
- Supports retrofit paths and collaborative dependency cross-referencing across existing docs
- 3 review modes: full, lean, solo
Adoption & trust: 1 installs on skills.sh; 21.2k GitHub stars; 3/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
You know which game system to build next but lack a consistent, gated GDD template and collaborative process to flesh out every section without losing dependencies.
Who is it for?
Solo or small game teams maintaining a systems-index-driven GDD tree in-repo who want structured, gate-checked design sessions per mechanic.
Skip if: Teams without a `design/gdd/` layout or systems index who only need one-off lore blurbs with no production gates.
When should I use this skill?
User invokes `/design-system <system-name>` or retrofit path; optional `--review full|lean|solo`; system name required unless systems-index offers next system.
What do I get? / Deliverables
You get an updated system GDD on disk with cross-referenced sections, review mode applied, and a clear handoff to implement or design the next indexed system.
- Updated per-system GDD file(s)
- Cross-referenced sections aligned to director gates
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
System GDDs are production design artifacts created while the product is being defined and built, so the canonical shelf is Build where design docs live alongside implementation. The skill writes and edits structured game design documentation (GDD sections, systems index, cross-refs)—classic docs work, not runtime code.
Where it fits
Turn a high-level combat idea into a scoped system GDD before committing engineering time.
Author the movement system GDD section-by-section while cross-referencing inventory dependencies.
Pick the next 'Not Started' entry from systems-index.md and run a lean review pass.
Retrofit launch-critical UI flow gaps in an existing GDD before milestone lock.
How it compares
Use instead of free-form chat GDD dumps—this is a gated, file-backed workflow skill, not a generic markdown generator.
Common Questions / FAQ
Who is design-system for?
Indie and solo game builders using Claude Code in a game-studio repo with GDD folders, systems indexes, and optional director gate docs.
When should I use design-system?
During Validate when scoping a mechanic into a spec, during Build when documenting systems before code, and during Ship prep when aligning launch-critical systems—invoke with a system name or let it propose the next indexed system.
Is design-system safe to install?
It requests Read, Write, Edit, Glob, Grep, Task, AskUserQuestion, and TodoWrite on your project files; review the Security Audits panel on this page before granting those tools in sensitive repos.
SKILL.md
READMESKILL.md - Design System
When this skill is invoked: ## 1. Parse Arguments & Validate Resolve the review mode (once, store for all gate spawns this run): 1. If `--review [full|lean|solo]` was passed → use that 2. Else read `production/review-mode.txt` → use that value 3. Else → default to `lean` See `.claude/docs/director-gates.md` for the full check pattern. A system name or retrofit path is **required**. If missing: 1. Check if `design/gdd/systems-index.md` exists. 2. If it exists: read it, find the highest-priority system with status "Not Started" or equivalent, and use `AskUserQuestion`: - Prompt: "The next system in your design order is **[system-name]** ([priority] | [layer]). Start designing it?" - Options: `[A] Yes — design [system-name]` / `[B] Pick a different system` / `[C] Stop here` - If [A]: proceed with that system name. If [B]: ask which system to design (plain text). If [C]: exit. 3. If no systems index exists, fail with: > "Usage: `/design-system <system-name>` — e.g., `/design-system movement` > Or to fill gaps in an existing GDD: `/design-system retrofit design/gdd/[system-name].md` > No systems index found. Run `/map-systems` first to map your systems and get the design order." **Detect retrofit mode:** If the argument starts with `retrofit` or the argument is a file path to an existing `.md` file in `design/gdd/`, enter **retrofit mode**: 1. Read the existing GDD file. 2. Identify which of the 8 required sections are present (scan for section headings). Required sections: Overview, Player Fantasy, Detailed Design/Rules, Formulas, Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria. 3. Identify which sections contain only placeholder text (`[To be designed]` or equivalent — blank, a single line, or obviously incomplete). 4. Present to the user before doing anything: ``` ## Retrofit: [System Name] File: design/gdd/[filename].md Sections already written (will not be touched): ✓ [section name] ✓ [section name] Missing or incomplete sections (will be authored): ✗ [section name] — missing ✗ [section name] — placeholder only ``` 5. Ask: "Shall I fill the [N] missing sections? I will not modify any existing content." 6. If yes: proceed to **Phase 2 (Gather Context)** as normal, but in **Phase 3** skip creating the skeleton (file already exists) and in **Phase 4** skip sections that are already complete. Only run the section cycle for missing/ incomplete sections. 7. **Never overwrite existing section content.** Use Edit tool to replace only `[To be designed]` placeholders or empty section bodies. If NOT in retrofit mode, normalize the system name to kebab-case for the filename (e.g., "combat system" becomes `combat-system`). --- ## 2. Gather Context (Read Phase) Read all relevant context **before** asking the user anything. This is the skill's primary advantage over ad-hoc design — it arrives informed. ### 2a: Required Reads - **Game concept**: Read `design/gdd/game-concept.md` — fail if missing: > "No game concept found. Run `/brainstorm` first." - **Systems index**: Read `design/gdd/systems-index.md` — fail if missing: > "No systems index found. Run `/map-systems` first to map your systems." - **Target system**: Find the system in the index. If not listed, warn: > "[system-name] is not in the systems index. Would you like to add it, or > design it as an off-index system?" - **Entity registry**: Read `design/registry/entities.yaml` if it exists. Extract all entries referenced by or relevant to this system (gr