Guide · Agent skill
How to use the Quick Design Spec agent skill (quick-design)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The quick-design skill is an agent skill for Claude Code, or a compatible agent that supports SKILL.md skills. When you want to change a small thing in a game, such as a balance number, a minor behaviour or a small added mechanic, it has the agent classify the change and write a short spec file under design/quick-specs/. This guide shows you what the skill does, how to install it, how to trigger it and what it needs before you start.
Quick Design SpecDonchitos/Claude-Code-Game-Studios · MIT Download the skill Quick start
- 1Download the ZIP. Get the quick-design ZIP from the skill's page on this site. It is MIT licensed.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use, or into your project's .claude/skills/ folder for one project.
- 3Make sure your repo has design docs. Confirm the repository has a design/ folder with GDD files and that hooks/yaml-helper.sh is present.
- 4Start Claude Code in the project. Open the repository in Claude Code or another agent that supports SKILL.md skills.
- 5Describe the change. Run the skill with a short description of the change, including any numbers, for example /quick-design increase jump height from 5 to 6 units.
- 6Confirm the classification. Answer the agent's question about the category, or pick the option that redirects a large change to /design-system.
- 7Review the spec. Open the file written under design/quick-specs/ and check the rationale, acceptance criteria and any GDD update note before you implement.
What does the quick-design skill make the agent do?
An agent skill is a folder containing a SKILL.md file with instructions the agent follows when a task matches. The quick-design skill covers the lightweight design path: changes that are too small for the full game design document (GDD) process but still need a written rationale. The full process is handled by the heavier /design-system path.
When you run it, the agent first reads the argument you give it and sorts the change into one of four categories. It then reads the existing GDD, the systems index if one exists, and any prior quick specs for the same system so the new spec does not contradict them. Finally it writes the spec to design/quick-specs/[name]-[date].md.
- Tuning: changing numbers or balance values in an existing system with no behavioural change
- Tweak: a small behavioural change that adds no new states, branches or systems
- Addition: a small mechanic added to an existing system, possibly with one or two new states
- New Small System: a standalone feature with no existing GDD, under about one week of implementation work
Install the quick-design skill in Claude Code or the Claude apps
Download the ZIP from the skill's page on this site. The skill is MIT licensed and its folder contains a SKILL.md file. You can install it in one of two places. For a personal setup that applies across your projects, unzip it into ~/.claude/skills/. For a single project, unzip it into the .claude/skills/ folder inside that project's repository.
If you use the Claude apps instead of the command line, upload the skill under Settings, then Capabilities, then Skills. Use the same ZIP you downloaded.
- Personal install: ~/.claude/skills/quick-design/SKILL.md
- Project install: [your-project]/.claude/skills/quick-design/SKILL.md
- Claude apps: Settings → Capabilities → Skills → upload the ZIP
~/.claude/skills/quick-design/SKILL.mdCheck the repository layout the skill expects
The skill is built for a game repository with a design/ folder. It reads design/gdd/ for GDD files, design/gdd/systems-index.md if that file exists, design/quick-specs/ for prior specs and design/game-brief.md when no GDD covers a system. For Tuning changes it also checks assets/data/ for the data file that holds the values.
The skill's config check calls hooks/yaml-helper.sh, which it reaches by a path two folders above the skill folder. Make sure that script is present in the repository, and that Bash is available so the config resolver can run. If the repository has no design docs at all, the skill will have little to read, so it works best in a project that already keeps design records.
- design/gdd/ for existing GDD files (optional but expected)
- design/quick-specs/ is where new specs are written
- assets/data/ for data files when tuning values
- hooks/yaml-helper.sh must be present for the config check
Trigger the skill with a plain description of the change
The skill accepts an argument described as a brief description of the change. Give it a short, concrete statement of what you want to alter, including the numbers if you have them. The agent will classify it and, if the category is unclear, ask you to confirm.
If you start without a description, the agent asks you to describe the change in plain text before it classifies it. Before drafting, it presents its inferred type through a question and lets you pick a different category or choose to be redirected to /design-system.
- Tuning example: increase jump height from 5 to 6 units
- Tweak example: make dash invincible on frame 1
- Addition example: add a parry window to the block mechanic
- New Small System example: achievement popup system
/quick-design increase jump height from 5 to 6 unitsRead the spec the skill produces
The spec format depends on the category. A Tuning spec is a single table of parameter, old value, new value and rationale, with a note on whether the new value sits inside the documented range of the GDD tuning knob. Tweak and Addition specs quote the current GDD rule, state the replacement rule precisely enough for a programmer to implement, and list affected systems and acceptance criteria. A New Small System spec is a trimmed GDD structure with scope, overview, core rules and an estimated implementation time.
If a change is too large, the skill stops and gives the verdict REDIRECTED, telling you to use /design-system instead. That happens when a change adds a system with significant cross-system dependencies, needs more than one week of work or changes a system's core rules.
- Every spec includes a date and a link to the GDD it relates to
- Tuning specs include acceptance criteria that point to the data file
- Tweak and Addition specs say whether a GDD update is required
Safety notes: scripts and network access
The skill runs one script. Its allowed tools include Bash, but only for the config resolver command that calls hooks/yaml-helper.sh with the resolve_config option for the automation and workflow keys. Its other allowed tools are for reading, searching, writing and editing files, plus asking you questions. The skill does not use the network.
Because the skill writes files, review the new spec in design/quick-specs/ before committing it to your repository. Check that the classification is right and that the values match what you intended.
- Runs scripts: yes, one config resolver call through hooks/yaml-helper.sh
- Uses network: no
- Writes and edits files in your repository, so review the output
What people use it for
- Rebalancing a weapon's damage or a character's movement speed with a written rationale attached to the change
- Adding a parry window to an existing block mechanic and recording the affected systems
- Writing a programmer-ready spec for a small standalone feature such as an achievement popup
- Recording a Tuning change with acceptance criteria that point to the value in assets/data/
Frequently asked questions
Is the quick-design skill free to use?
The skill is published under the MIT licence, as stated on its page. Check the licence file in the repository for the full terms before you reuse or redistribute it.
What do I need to run quick-design?
You need Claude Code or a compatible agent that supports SKILL.md skills, a repository containing a design/ folder structure and hooks/yaml-helper.sh, and Bash available for the config resolver. The skill is built around game design, so it is not suited to non-game software.
Where do I put the skill folder?
Unzip the downloaded ZIP into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project for that project only. In the Claude apps you can instead upload it under Settings, then Capabilities, then Skills.
Can quick-design write a full game design document?
No. It is the lightweight path for small changes. Work that needs a full GDD, such as a large new system or anything over about one week, is redirected to /design-system.
Why does the skill ask me questions?
It asks you to confirm the change category before drafting, and it can ask you to describe the change if you gave no argument. This lets you correct a wrong classification before a spec is written.
What should I do if the skill finds no design docs?
The skill expects a design/ folder layout. If it finds no GDD for the system, it uses design/game-brief.md and the relevant story instead and says so. If the repository has no design structure at all, it will have little to read, so add the folder layout first.
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 quick-design if you make frequent small balance or tuning changes in a game repository that already keeps design docs in a design/ folder, and you want each change recorded with a rationale. Pick something else if your project has no design structure, is not a game, or involves large systems, since the skill redirects those to /design-system.
Download the skill