Guide · Agent skill
How to use the Game Balance Checker agent skill (balance-check)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Game Balance Checker is an agent skill that asks your coding agent to review a game's balance data and design document for outliers, dominant strategies, stalled progression and economy imbalances. It is for game designers and developers who keep balance numbers in YAML or data files and want a structured second look. After this guide you will know what the skill does, how to install it, how to trigger it, and when it will correctly refuse to produce a result.
Game Balance CheckerDonchitos/Claude-Code-Game-Studios · MIT Download the skill Quick start
- 1Download and unzip. Download the ZIP from this page and unzip it so the balance-check folder with SKILL.md is in place.
- 2Place the skill folder. Move it to ~/.claude/skills/ for personal use or to your project's .claude/skills/ folder, or upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
- 3Prepare balance data. Make sure balance data files exist under assets/data/ and design/balance/.
- 4Prepare the design document. Add a game design document under design/gdd/ that states intended targets, and optionally design/registry/entities.yaml.
- 5Ask for a check. Request a balance check for a named system or a data file path.
- 6Read the verdict. Review the health summary, outliers and any NOT ASSESSED sections, then decide what to tune.
What is an agent skill and what does this one do?
An agent skill is a folder containing a SKILL.md file that tells a compatible agent, such as Claude Code, how to perform a specific task. This skill, named balance-check, is built for game balance work. When it runs, the agent reads balance data files under assets/data/ and design/balance/, reads the game design document under design/gdd/, and checks values against the targets those documents state.
The skill looks for values outside their intended ranges, strategies that dominate all others, stalled progression, and economy loops such as unbounded resource generation. It then produces a report with a health verdict: NOT ASSESSED, HEALTHY, CONCERNS or CRITICAL ISSUES.
- Combat: DPS, time-to-kill, dominant options and damage type interactions
- Economy: resource faucets and sinks, acquisition rates, item pricing
- Progression: XP and power curves, dead zones, power spikes
- Loot: rarity distribution, pity timer math, inventory pressure
Install the balance-check skill
Download the ZIP from this page and unzip it. For a personal install, place the balance-check folder in ~/.claude/skills/. For a single project, place it in your project's .claude/skills/ folder. Alternatively, in the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP.
The package contains one file, SKILL.md. The skill's bundled helper script lives at hooks/yaml-helper.sh, which the skill expects to find relative to its own folder, so keep the folder structure intact.
- Personal: ~/.claude/skills/balance-check/
- Project: .claude/skills/balance-check/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Check your project is ready before you run it
The skill needs real input. It will not invent a balance report. Before running it, make sure your project has balance data files under assets/data/ and design/balance/, and a game design document under design/gdd/ that states intended targets. If design/registry/entities.yaml exists, the skill reads its constants and formulas first, because those hold the cross-document figures.
The skill also needs Bash access so it can run the bundled yaml-helper.sh config resolver. Without the data and design targets, expect a NOT ASSESSED result.
- Claude Code or another SKILL.md-compatible agent
- Balance data files under assets/data/ and design/balance/
- A game design document under design/gdd/ (design/registry/entities.yaml is optional)
- Bash access for the yaml-helper.sh resolver
Trigger the skill with a natural request
Ask the agent in plain language, for example asking it to check game balance for a named system. The skill's argument hint is [system-name|path-to-data-file], so you can name a system such as combat or economy, or give a path to one data file. If you give a file path, the skill loads that file directly and infers the domain from its contents. If you give no argument, the skill asks which system to check.
Because the skill is triggered by its description, phrases like 'check game balance' are the natural starting point.
- "Check game balance for the economy in assets/data/economy.yaml"
- "Check game balance for combat"
- "Check game balance for the loot system"
Read the report and the NOT ASSESSED verdict
The report lists the data sources analysed, a health summary, a table of outliers with expected range, actual value and issue, degenerate strategies, a progression analysis, prioritised recommendations, and values that need attention. Each value is compared with a target from the registry or the design document. A value with no stated range is listed as not judged rather than guessed.
NOT ASSESSED is a valid result, not a failure of the tool. It appears when required inputs are missing, when a section needs targets that no document provides, or when there is nothing to analyse. The report names what was missing and which skill produces it, such as /design-system.
- CRITICAL ISSUES: a dominant strategy, a progression that stalls or cannot be completed, or an economy loop with no sink
- CONCERNS: outliers or curve problems that a tuning pass can fix
- NOT ASSESSED: missing data or targets, named in the report
- HEALTHY: every value judged against a stated target with no findings
Safety notes: scripts and network
This skill runs a script: the bundled yaml-helper.sh config resolver, through Bash. It does not use the network. Its allowed tools are Read, Glob, Grep, Write, AskUserQuestion and that one Bash pattern. Review the script before installing if you work on sensitive projects.
The skill can write a report to design/balance/ if you choose that option at the end. It does not make final balance decisions for you.
- Runs scripts: yes (yaml-helper.sh via Bash)
- Uses network: no
- Writes files only when you choose to save the report
What people use it for
- Reviewing combat weapon DPS and time-to-kill tiers against the design targets
- Looking for unbounded resource loops in an economy defined in YAML
- Checking whether an XP curve creates dead zones or sudden power spikes
- Checking loot rarity and pity timer math against stated targets
Frequently asked questions
How do I install the balance-check agent skill?
Download the ZIP from this page and unzip it. Place the balance-check folder in ~/.claude/skills/ for personal use or in your project's .claude/skills/ folder, or upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
What do I need to run the Game Balance Checker?
You need Claude Code or a SKILL.md-compatible agent, balance data files under assets/data/ and design/balance/, a game design document under design/gdd/, and Bash access to run the bundled yaml-helper.sh resolver. The registry file design/registry/entities.yaml is optional.
Is the balance-check skill free to use?
The source lists the licence as MIT. Check the repository's licence file for the full terms before you use or modify it.
Why does the skill return NOT ASSESSED?
It returns NOT ASSESSED when required data files or design targets are missing. The skill is designed to report this rather than guess, so add balance data and a design document with stated targets and run it again.
Does the balance-check skill need the internet?
No. The skill is listed as not using the network. It runs a bundled bash script for config resolution and reads your local files.
Can this skill replace playtesting or simulation?
No. The analysis depends on the accuracy of the targets it is given and on the agent's reasoning, not on playtesting or simulation. Use it as a structured second look, then validate final balance decisions with play data.
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 balance-check if you are a game designer or developer with balance values in data files and a design document that states targets, and you want a structured second look for outliers and degenerate loops. Skip it if your project lacks balance data or design targets, since it will return NOT ASSESSED, or if you need final balance decisions, which require playtesting or simulation.
Download the skill