Guide · Agent skill
How to use the Design Review agent skill for game design docs
Updated · written with AI from the project's own documentation and checked against our catalogue data
The design-review skill is an agent skill for Claude Code that reviews one game design document (GDD) before it goes to programmers. It checks that required sections are present, that facts and numbers do not contradict each other or the project's shared registry, and that the design can be built. This guide covers what the skill does, how to install it, how to trigger it with plain requests, what it needs, and the safety points to know before you run it.
Design ReviewDonchitos/Claude-Code-Game-Studios · MIT Download the skill Quick start
- 1Get the skill files. Download the ZIP from this skill's page on the directory.
- 2Install the skill. Unzip into ~/.claude/skills/ for all projects or into .claude/skills/ in one project, or upload the ZIP at Settings → Capabilities → Skills.
- 3Check the project layout. Make sure the project has the .claude folder with hooks, scripts and docs, and a design/gdd folder. Add design/registry/entities.yaml if you use the registry.
- 4Make a request. Ask Claude to review a specific GDD path, and add --review full, lean or solo if you want a particular mode.
- 5Read the verdict and log. Check the verdict and findings the agent reports, and the review log saved under design/gdd/reviews/.
- 6Revise and re-run. Edit the document to fix the findings, then run the review again. An unchanged document reuses the prior verdict.
What the design-review skill makes the agent do
An agent skill is a folder with a SKILL.md file that tells Claude how to carry out a specific task. This skill is for one job: reviewing a single design document before handoff. The source describes it as reviewing a design document for completeness, internal consistency, implementability, and design standards.
The review depends on the workflow tier for the document. At the full tier, all 8 sections are validated and any missing section blocks approval. At the standard tier, five required sections (Overview, Detailed Rules, Edge Cases, Dependencies, Acceptance Criteria) block if missing, while Formulas blocks only when the system defines numeric rules. Player Fantasy and Tuning Knobs are advisory and only warn. At the minimal tier, no GDD is expected, and if one exists the five standard sections are checked in an advisory way.
- Checks that required sections are present for the workflow tier
- Compares numbers and facts against design/registry/entities.yaml, or against related GDDs if the registry has no entry for the system
- Checks that systems named in Dependencies have a GDD file in design/gdd/
- Checks the document against game-concept.md or design/game-brief.md and design/narrative/ files when they exist
- Saves review logs under design/gdd/reviews/
Install the design-review skill
You can install the skill in either of two ways. Download the ZIP from the skill's page on this directory and unzip it into your user skills folder, ~/.claude/skills/, or into a project's own .claude/skills/ folder. Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
After installing, check that the skill folder contains SKILL.md. The skill also refers to a project's .claude folder for hooks, scripts and docs, so a project-level install needs that folder alongside it.
- Option A: unzip into ~/.claude/skills/ for all your projects
- Option B: unzip into .claude/skills/ inside one project
- Option C: upload the ZIP in the Claude apps at Settings → Capabilities → Skills
How to trigger the review with a natural request
The skill is user-invocable and takes a path to the design document as its main argument. You can also pass --review with full, lean or solo. Without a flag, the mode comes from the project's configuration. Plain requests such as the example below also work, because the agent matches the request to the skill's description.
Phase 1 runs a freshness check before reading anything. If the document, this skill file, the registry and related files are all unchanged since the last review, the agent reports the prior verdict instead of repeating the work.
- Example request: Review design/gdd/combat.md before I hand it to programmers.
- Example request: Run a lean design review on design/gdd/inventory.md.
- Example request: Check the crafting GDD for missing sections and contradictions with the registry.
argument-hint: [path-to-design-doc] [--review full|lean|solo]Choose a review mode: full, lean or solo
The mode controls how thorough the review is. Full runs all phases and delegates to specialist sub-agents in Phase 3b. Lean runs all phases in one session with no specialist agents, which is faster. Solo runs Phases 1 to 4 only, with no delegation and no Phase 5 next-step prompt, and is meant for use inside other skills.
The older --depth flag was renamed to --review. If you pass --depth, the agent treats it as --review and notes the rename. If you pass both, --review wins and --depth is ignored.
- full: complete review with specialist agent delegation
- lean: all phases, no specialist agents
- solo: Phases 1 to 4 only, for use from another skill
Requirements and safety notes
The skill needs Claude Code with the project's .claude folder, because it references hooks, scripts and docs. It needs a bash shell for its helper scripts: yaml-helper.sh, review-receipts.sh and gdd-structure-check.sh. The project should have a design/gdd folder, and optionally design/registry/entities.yaml. The skill is set to run scripts and does not use the network.
The skill has Write and Edit permissions, so it can write review logs and related files into your repository. If you do not want that, do not use it on that repository. The shell commands it may run are limited to the patterns listed in its allowed-tools setting, which include the three helper scripts and grep commands. The source also says the review is automated and can miss defects, so it is not final sign-off.
- Runs scripts: yes, bash helper scripts from the project's .claude folder
- Uses network: no
- Writes review logs under design/gdd/reviews/ and can edit files
- The registry ships as an empty stub until /design-system populates it
Tips for getting useful results
Review one document at a time, because the skill is built for a single GDD. Keep the registry current for the system you are reviewing, since the agent checks facts against it first. Read the prior findings in the review log before you revise, because a document that failed review has not changed and re-reviewing it will not change the result.
If you want a fresh pass after editing, the document must actually change; the skill will not offer a partial re-review of only the changed sections. Large GDDs over 40 KB are read in ranges by heading, so keep headings clean so the agent can navigate them.
- Revise the document before asking for another review when the last verdict was NEEDS REVISION or MAJOR REVISION NEEDED
- Keep the registry entry for the system up to date
- Use the workflow tier that matches your project's rigour setting
- Treat a passing review as a check, not as proof of completeness
What people use it for
- A solo developer checks a combat GDD for missing Edge Cases and Acceptance Criteria before starting implementation.
- A design lead applies the same section checklist to every GDD in a project's design/gdd folder.
- A studio using the Claude Code Game Studios template keeps review logs in design/gdd/reviews/ for each document.
- A designer runs a solo review from inside another skill to get a quick consistency check during a larger workflow.
Frequently asked questions
How do I install the design-review skill?
Download the ZIP from the skill's page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
What do I need to run design-review?
You need Claude Code with the project's .claude folder, a bash shell for the helper scripts, and a project layout with design/gdd. The registry file design/registry/entities.yaml is optional but recommended.
Is design-review free to use?
The source lists the licence as MIT. This guide does not cover pricing or any cost for Claude Code itself, so check those terms separately.
Does design-review need an internet connection?
The skill is listed as not using the network. It runs local bash helper scripts and reads files in your project.
Can it review documents that are not game design docs?
No. The section rules are specific to GDD-style design documents, so it is not a fit for non-game documents or projects without that format.
Why did the agent skip my review?
If the document and the skill file are byte-identical to the last review, and the registry and related files are unchanged, the agent reuses the prior verdict. Edit the document to force a new review.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use design-review if you write GDDs before implementation and want the same completeness and consistency checklist applied to each one, especially in a Claude Code Game Studios setup. Pick something else if your documents are not game design docs, if you need a final sign-off on design quality, or if you do not want the agent writing review logs and related files into your repository.
Download the skill