Turn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Skill Test Spec: /patch-notes
Skill Summary
/patch-notes is a Sonnet-tier skill that turns a release's changes into
player-facing patch notes. Before reading any history it classifies recent
commits as Game or Framework / maintenance (Unclear counts as Framework), uses
only the Game commits, and says how many of how many it used. It gathers change
data from production/releases/[version]/changelog.md, the version's entry in
docs/CHANGELOG.md, and — as a fallback — git log from the previous release
tag. It checks for a tone guide (.claude/docs/technical-preferences.md,
docs/PATCH-NOTES-STYLE.md, design/community/tone-guide.md) and a patch-notes
template (docs/patch-notes-template.md,
.claude/docs/templates/patch-notes-template.md), removes internal-only
changes, and translates the rest into player language in Brief, Detailed
(default) or Full style — or in the template's structure when one exists, saying
which template it used. No director gates are used. The skill asks "May I write
these patch notes to docs/patch-notes/[version].md, and an archive copy to
production/releases/[version]/patch-notes.md?" — naming both files — and on
approval writes both. Verdicts:
COMPLETE (notes generated and saved) or BLOCKED (no changelog data and no git
history, or no Game commit in the history).
Static Assertions (Structural)
Checked against the SKILL.md by /skill-test spec — no fixture needed.
- Has required frontmatter fields:
name,description,argument-hint,user-invocable,allowed-tools - Has ≥2 phase headings
- Contains verdict keywords: COMPLETE, BLOCKED
- Contains "May I write" language (skill writes patch notes file)
- Has a next-step handoff (
/release-checklist, community-manager tone review)
Director Gate Checks
None. Patch notes generation is a fast compilation task; no gates are invoked.
Fixture Defaults
Every case's project.yaml sets modes.rigor: minimal and
modes.automation: collaborative, with no project.local.yaml, unless its own
Fixture says otherwise. Rules: studio-tests/CLAUDE.md §
Fixture defaults.
Test Cases
Case 1: Happy Path — Changelog filtered to player-facing entries
Fixture:
docs/CHANGELOG.mdhas av0.4.0entry with 5 items:- "Add dual-wield melee system" (player-facing)
- "Fix crash on level transition" (player-facing)
- "Add enemy patrol AI" (player-facing)
- "Refactor input handler to use event bus" (internal only)
- "Update dependency: Godot 4.6" (internal only)
- Git history since the previous tag holds the Game commits behind those items
- No tone guide and no patch-notes template exist
Input: /patch-notes v0.4.0
Expected behavior:
- Skill classifies the recent commits and says how many of how many it used
- Skill reads the
v0.4.0entry indocs/CHANGELOG.md - No tone guide is found, so the default tone applies; no template is found,
so the built-in Detailed style (the default
--style) is used - Skill keeps the 3 player-facing items and removes the 2 internal ones
- Skill rewrites the items in player language (no task IDs, no internal system names)
- Skill presents the notes with a count of changes by category and the list of excluded internal changes
- Skill asks "May I write these patch notes to
docs/patch-notes/v0.4.0.md, and an archive copy toproduction/releases/v0.4.0/patch-notes.md?" - User approves; both files are written; verdict COMPLETE
Assertions:
- Only the 3 player-facing items appear in the notes; the 2 internal items are listed separately as excluded, for review
- Entries are written in plain language without internal task IDs or system names
- Notes use the built-in Detailed style (Highlights, New Content, … Known Issues) — the default when no
--styleis given and no template exists - "May I write" prompt naming
docs/patch-notes/v0.4.0.mdappears before any file is written - Verdict is COMPLETE after the write
Case 2: No Changelog File — Falls back to git history
Fixture:
- Neither
production/releases/v0.4.0/changelog.mdnordocs/CHANGELOG.mdexists - Tag
v0.3.0exists; the rangev0.3.0..HEADholds 6 Game commits and 2 Framework / maintenance commits (one touching a hook, one touching CI)
Input: /patch-notes v0.4.0
Expected behavior:
- Skill classifies the commits, keeps the Game commits, excludes the 2 framework commits, and says how many of how many it used
- Skill finds no changelog source and uses
git logfromv0.3.0to HEAD as the fallback - Skill does NOT stop with BLOCKED — the "No changelog data found … Run
/changelog [version]first" path requires the git history to be empty or unavailable as well - Skill generates notes from the Game commits only
- Skill asks "May I write" before writing
Assertions:
- Skill does not crash and does not stop with BLOCKED while git history is available
- Skill falls back to
git logfrom the previous tag (v0.3.0) to HEAD - Output states how many of how many commits were used
- The 2 framework / maintenance commits do not appear in the patch notes
- "May I write" prompt appears before any file is written
Case 3: Tone Guidance from Design Folder — Incorporated into output
Fixture:
docs/CHANGELOG.mdhas av0.4.0entry with player-facing items; git history holds the matching Game commitsdesign/community/tone-guide.mdexists with guidance: "upbeat, encouraging tone; avoid passive voice"docs/PATCH-NOTES-STYLE.mddoes not exist and.claude/docs/technical-preferences.mdhas no tone, voice or style fields- No patch-notes template exists
Input: /patch-notes v0.4.0
Expected behavior:
- Skill reads the changelog entry
- Skill checks the three tone sources and finds
design/community/tone-guide.md - Skill extracts the guide's instructions and applies them to the language and framing of the notes, in place of the built-in default tone
- Structure stays the built-in Detailed style
- Skill presents the notes, asks "May I write", writes on approval
Assertions:
- Skill checks the tone sources in Phase 2b, including
design/community/tone-guide.md - The tone guide's instructions are applied in place of the built-in default tone
- Entries use active voice ("Fixed a crash when…", "You can now…"), not passive ("A crash was fixed")
- Tone guidance changes wording only — the output structure is still the Detailed style
Case 4: Patch Note Template Exists — Used instead of the built-in styles
Fixture:
.claude/docs/templates/patch-notes-template.mdexists with a header block, the sections## New,## Fixedand## Known Issues, and a footerdocs/CHANGELOG.mdhas av0.4.0entry with one new feature and one bug fix, both player-facing; git history holds the matching Game commits
Input: /patch-notes v0.4.0 --style full
Expected behavior:
- Skill globs
docs/patch-notes-template.mdand.claude/docs/templates/patch-notes-template.md; finds and reads the second - Skill uses the template as the output structure instead of the built-in
Brief / Detailed / Full templates — even though
--style fullwas passed - The new feature goes under
## New, the fix under## Fixed - The template's header and footer are preserved
- The output says the template was used and that it replaced
--style full - Skill asks "May I write" and writes on approval
Assertions:
- Skill globs both template locations before generating
- The template's structure replaces the built-in style — no "Developer Commentary" section from the Full style despite
--style full - The new feature is placed under
## Newand the fix under## Fixed - The template's header and footer are preserved in the output
- Output notes that
.claude/docs/templates/patch-notes-template.mdwas used, and that it replaced the requested--style full
Case 5: Gate Compliance — No gate; community-manager is separate
Fixture:
docs/CHANGELOG.mdhas av0.4.0entry with player-facing items; git history holds the matching Game commitsproject.yamlsetsmodes.review_mode: full
Input: /patch-notes v0.4.0
Expected behavior:
- Skill compiles patch notes; no director gate is spawned (the skill resolves
only
automation, neverreview_mode) - Skill self-reviews the notes (Phase 5), then presents them and asks to write
- Next steps suggest
/release-checklistand sharing the draft with the community-manager for tone review before posting publicly - User approves; notes are written; verdict COMPLETE
Assertions:
- No director gate is invoked regardless of review mode
- Output suggests (but does not require) a community-manager tone review before posting
- Skill proceeds directly from compilation and self-review to the "May I write" prompt
- Verdict is COMPLETE
Case 6: Provenance Stop — Zero Game commits
Fixture:
git log --oneline -20shows 20 commits, all touching the framework or tooling — subjects such as "fix: session-start hook timeout", "docs: skill catalog", "ci: cache the test runner" — and none names a game system indesign/or the code root- Neither
production/releases/v0.4.0/changelog.mdnordocs/CHANGELOG.mdexists
Input: /patch-notes v0.4.0
Expected behavior:
- Before Phase 2, skill classifies the sampled commits: 0 Game, 20 Framework / maintenance
- Skill stops with "The git history in this repo does not appear to belong to [game] …", describing what the commits actually cover
- No notes are generated and nothing is written; verdict BLOCKED
Assertions:
- Output names the classification result — 0 of 20 commits are Game commits
- Output contains the "does not appear to belong to" stop, not notes written from framework commits (no "Fixed an issue where …" line from a hook fix)
- No "May I write" prompt appears and no file is written
- Verdict is BLOCKED, not COMPLETE
Case 7: No Changelog Data — No changelog and no git history
Fixture:
- Neither
production/releases/v0.4.0/changelog.mdnordocs/CHANGELOG.mdexists - The project directory is not a git repository, so
git logreturns nothing
Input: /patch-notes v0.4.0
Expected behavior:
- The sampled log is empty, so the provenance check is skipped — there is nothing to classify
- Phase 2 finds no changelog source and no git history; skill outputs "No
changelog data found for v0.4.0. Run
/changelog v0.4.0first to generate the internal changelog, then re-run/patch-notes v0.4.0." - Nothing is generated or written; verdict BLOCKED
Assertions:
- The "does not appear to belong to" provenance stop is NOT shown — an empty history is not a wrong history
- Output contains "No changelog data found for v0.4.0" and recommends
/changelog v0.4.0 - No notes are generated, no "May I write" prompt appears, and no file is written
- Verdict is BLOCKED
Protocol Compliance
- Runs the provenance check before reading history, uses only Game commits, and says how many were used
- Reads the version's changelog entry (
production/releases/[version]/changelog.md,docs/CHANGELOG.md) before falling back togit log - Filters entries to player-facing items only, and lists the excluded internal changes for review
- Rewrites entries in plain language without internal IDs
- Always asks "May I write" before writing patch notes
- No director gates are invoked
- Declares
model: sonnet— it writes player-facing copy
Coverage Notes
- A missing version argument (the skill asks before proceeding) is not tested.
- The case where all changelog entries are internal (zero player-facing items) is not tested.
- The community manager consultation noted in Case 5 is advisory; a separate skill or manual review handles that step.