Guide · Agent skill
How to use the Milestone Progress Review agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The milestone-review skill is an agent skill for Claude Code that produces a structured milestone progress review for a software project: feature completeness, open bugs, code health markers, risk, velocity and an advisory go/no-go recommendation. This guide is for studio or indie game leads, producers and developers who want to install it, run it at a checkpoint or before a deadline, and understand what it will and will not report. By the end you will know how to install it, which folders it needs, how to start a review and how to read the output.
Milestone Progress ReviewDonchitos/Claude-Code-Game-Studios · MIT Download the skill Quick start
- 1Confirm the folder layout. Check that the project has .claude/hooks/yaml-helper.sh, the .claude/docs files and the production folders the skill reads. Missing folders will produce NOT ASSESSED sections.
- 2Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or the project's .claude/skills/ folder for one project. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.
- 3Write or confirm milestone definitions. Create milestone definitions by hand from .claude/docs/templates/milestone-definition.md in production/milestones/. The skill does not create them.
- 4Add sprint reports and bug files. Keep sprint reports in production/sprints/ and bug files in production/qa/bugs/ so the review can aggregate them and count open bugs by severity.
- 5Start the review. Run /milestone-review with a milestone name or current, optionally adding --review full, lean or solo.
- 6Check the NOT ASSESSED lines. Read the Overview and any NOT ASSESSED — NO DATA lines first, and fill the missing inputs before relying on a section.
- 7Use the recommendation with judgement. Read the scope recommendations and go/no-go assessment as advisory input and make the final decision yourself.
What an agent skill is and what milestone-review makes the agent do
An agent skill is a folder containing a SKILL.md file that gives a compatible agent a set of instructions, the tools it may use and, here, a few helper scripts. Once the skill is installed, you start it by name and the agent follows its steps instead of improvising.
With milestone-review installed, the agent reads hand-written milestone definitions and sprint reports, scans for TODO, FIXME and HACK markers, counts open bugs by severity, and writes a review file named [milestone-name]-review.md into the project. The report covers feature completeness (fully complete, partially complete, blocked, not started), quality metrics, code health, risk assessment, velocity analysis, scope recommendations and a go/no-go assessment.
- Feature completeness, split into fully complete, partially complete, blocked and not started
- Open S1, S2 and S3 bug counts and test coverage
- TODO, FIXME and HACK counts and critical technical debt
- Risk assessment and velocity analysis across sprints
- Protect, at-risk and cut-candidate scope recommendations
- An advisory go/no-go recommendation
Check the requirements before you install
The skill is built for one specific project layout. It needs Claude Code or a compatible SKILL.md agent, the Claude Code Game Studios folder structure including .claude/hooks/yaml-helper.sh and the .claude/docs files it references, and Bash available so the config script can run.
The skill reads these folders: production/milestones for definitions, production/sprints for sprint reports, production/sprint-status.yaml for blocked stories, production/epics for story files, and production/qa/bugs for bug files. production/risk-register is optional. Milestone definitions are written by hand from .claude/docs/templates/milestone-definition.md, because no skill creates them.
- Claude Code or a compatible SKILL.md agent
- Claude Code Game Studios folder structure, including .claude/hooks/yaml-helper.sh and .claude/docs files
- Bash available to run the yaml-helper.sh config script
- Projects without these folders will get mostly NOT ASSESSED sections
Install the milestone-review skill
Download the ZIP from the skill's page on this directory. The package contains the SKILL.md file. You can install it in one of three places depending on how you work.
For a personal install that applies everywhere, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. If you use the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal: unzip into ~/.claude/skills/
- Project only: unzip into your project's .claude/skills/
- Claude apps: upload the ZIP under Settings → Capabilities → Skills
Trigger a review with a natural request or the skill name
The skill is user-invocable, so you can start it by name with an optional argument. The argument is either a milestone name or current, which selects the most recently modified milestone definition, skipping files ending in -review.md. You can also add --review with full, lean or solo to override the review mode set in your project config for that run.
The skill runs its config check first, which resolves the keys review_mode, automation and workflow. If a project has no config block, the defaults in .claude/docs/config-resolution.md apply.
- /milestone-review current
- /milestone-review [milestone-name]
- /milestone-review current --review lean
bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflowRead the output and handle missing data
The skill is built to refuse to fabricate results. Before writing any report it records each input as FOUND or ABSENT. Any section whose input is absent is marked NOT ASSESSED — NO DATA rather than given a clean pass. If every required input is absent, the whole verdict is NOT ASSESSED — NO DATA, and the report names what was missing and which skill produces it.
Treat a NOT ASSESSED line as a gap to fill, not a green result. A zero from a scan with no files to scan is also reported as unverified, not as zero.
- FOUND or ABSENT is recorded for each input before a section is written
- NOT ASSESSED — NO DATA means the input was missing, not that the result was good
- Sprint reports that contribute nothing are listed so the milestone history stays complete
Safety notes: scripts, file writes and network
The skill runs a script. Its Bash permission is limited to the yaml-helper.sh resolve_config command, and the script is used to read the project config. The skill also has Write access because it saves the review file into the project. Its declared network use is none.
Because the recommendation is advisory and depends on the quality of the input files, a person should check the sprint reports, bug files and blocked-story records before making a release decision.
- Runs scripts: yes, through Bash limited to yaml-helper.sh resolve_config
- Writes the review file [milestone-name]-review.md into the project
- Uses network: no
- Any collaborative question it asks follows the project's automation-modes doc
What people use it for
- A studio lead preparing a checkpoint review for a game milestone that uses the Claude Code Game Studios structure
- A producer who keeps sprint reports and bug files in the expected folders and wants a consistent milestone summary each time
- A developer who wants a quick list of blocked stories and open S1 to S3 bugs before a release decision
- An indie team checking which features can be cut to protect a deadline, using the Protect, At Risk and Cut Candidates lists
Frequently asked questions
How do I install the milestone-review skill?
Download the ZIP from the skill's page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps you can upload the ZIP under Settings → Capabilities → Skills instead.
What does the milestone-review skill need to run?
It needs Claude Code or a compatible SKILL.md agent, the Claude Code Game Studios folder structure including .claude/hooks/yaml-helper.sh and the .claude/docs files it references, and Bash available to run the config script.
Is milestone-review free to use?
The source lists its licence as MIT. It does not state any price, so check the licence text on the project's repository for the terms.
Can I use milestone-review on a project that is not a game?
Its file layout and templates are specific to the Claude Code Game Studios framework, so it is not designed for non-game or non-studio projects. Without the expected production folders most sections will be NOT ASSESSED.
Why does my review say NOT ASSESSED — NO DATA?
The skill marks a section that depends on a missing input as NOT ASSESSED rather than inventing a result. Add the missing files, such as milestone definitions, sprint reports or bug files, and run the review again.
Does milestone-review make the go/no-go decision for me?
No. The recommendation is advisory and depends on the quality of the input files, so a person with project knowledge should make the final call.
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
Milestone-review is worth installing if your project follows the Claude Code Game Studios structure and you want a consistent, honest summary of a milestone before a checkpoint or deadline. If your project does not keep milestone definitions, sprint reports and bug files in the expected folders, or you want an automated release decision, pick a different tool or a manual review template.
Download the skill