agentleFS
DonchitosDonchitos/Claude-Code-Game-Studios/.claude/skills/write-changelog/SKILL.md

write-changelog

Skill39k starsChanged 7 days agoMITView on GitHub

Writes a changelog from git commits and sprint data. Use for an internal or player-facing one.

13 other projects use a version of this.

Adopted by

Steady: 0 new projects took it in the last 4 weeks, none the 4 weeks before.thin data

Week of Sep 20: 0 new projectsWeek of Sep 27: 0 new projectsWeek of Oct 4: 0 new projectsWeek of Oct 11: 0 new projectsWeek of Oct 18: 0 new projectsWeek of Oct 25: 0 new projectsWeek of Nov 1: 0 new projectsWeek of Nov 8: 0 new projects
Sep 2026Oct 2026Nov 2026
New projects taking a version of this file each week, over the 8 weeks our latest run read: only 0 in all, so this is a hint, not a trend.

Most recently taken up by

Who's talking about Donchitos/Claude-Code-Game-Studios

The biggest 5 of 74 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 74

Talked about on GitHub, YouTube and Bluesky (74 times).

On GitHub · 39

34 more on GitHub

On YouTube · 23

18 more on YouTube

On Bluesky · 12

7 more on Bluesky

The file

Show its rules and text

We split this skill into the rules it gives an agent

21 rules. 0 are common, 15 are distinctive, and 6 are very specific to this project.

  • 0

    Common

    Most of the 13 edited versions we read keep these.

  • 15

    Distinctive

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read the injected commit subjects above.

    line 36
  2. Distinctive:

    If no commit in the range is this game's, say so and stop:

    line 62
  3. Distinctive:

    Read the argument for the target version or sprint number.

    line 89
  4. Distinctive:

    Verify the repository is initialized: run git rev-parse --is-inside-work-tree to confirm git is available.

    line 91
  5. Distinctive:

    Read the git log since the last tag or release:

    line 104
  6. Distinctive:

    If no tags exist, bound the range explicitly — git log --oneline -n 100.

    line 110
  7. Distinctive:

    If 100 commits does not reach far enough back, say so and ask for a start ref rather than widening blindly.

    line 113
  8. Very specific:

    Read sprint reports from production/sprints/ for the relevant period to understand planned work and context behind changes.

    line 116
  9. Very specific:

    Read completed design documents from design/gdd/ for any new features implemented during this period.

    line 118
  10. Distinctive:

    After presenting the changelogs, ask the user:

    line 232
  11. Very specific:

    Check whether docs/CHANGELOG.md exists before asking.

    line 239
  12. Distinctive:

    If the user selects [A]: append the new internal changelog entry to the top of the existing file (newest entries first).

    line 241
  13. Distinctive:

    If the user selects [B]: overwrite the file with the new changelog.

    line 243
  14. Distinctive:

    If the user selects [C]: stop here without writing.

    line 244
  15. Very specific:

    After a successful write: Verdict: CHANGELOG WRITTEN — changelog saved to docs/CHANGELOG.md.

    line 246
  16. Distinctive:

    If the user declines: Verdict: COMPLETE — changelog generated.

    line 247
  17. Very specific:

    Use /patch-notes [version] to generate a styled, saved version for public release.

    line 253
  18. Very specific:

    Use /release-checklist before publishing the changelog externally.

    line 254
  19. Distinctive:

    Never expose internal code references, file paths, or developer names in the player-facing changelog

    line 258
  20. Distinctive:

    If a commit message is unclear, check the associated files and sprint data for context

    line 260
  21. Distinctive:

    If the git history is messy (merge commits, reverts, fixup commits), clean up the narrative rather than listing every commit literally

    line 263

“Common” is measured: kept by at least 6 in 10 of the 13 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation

Automation mode: Resolve modes.automation (project.local.yaml → project.yaml → default collaborative). Every question and every file write follows .claude/docs/automation-modes.md (collaborative asks always · guided major-only · autonomous logs and proceeds; automation_always_ask categories always prompt).

Changelog

Recent History

Recent commits:

!git log --oneline -30 2>/dev/null || true

Recent tags (newest first):

!git tag --list --sort=-v:refname 2>/dev/null | head -5

Provenance check — before trusting the history above

The commits above may not belong to this game. This skill's history blocks are auto-resolved before the body runs, so the read has already happened — what this check governs is whether that output is usable, not whether it is fetched.

  1. Read the injected commit subjects above. If there are none — the log is empty or git is unavailable — skip this check: there is nothing to classify, and Phase 1's no-history branch is the right stop.
  2. Classify each one as Game (mechanics, content, balance, art, audio, UI, or a bug in those), Framework / maintenance (subjects naming skills, hooks, agents, the test plan, CI, or the framework's own docs), or Unclear — and treat Unclear as Framework.
  3. Decide from the counts:
    • At least one Game commit → proceed using only those, and state how many of how many you used.
    • Zero Game commits → stop, using the message below.

Filter per commit; a repo containing maintenance work is not a wrong repo. Every project on this framework accumulates commits touching hooks, CI and skills — the game repo is the framework repo, so stopping on them would fire on virtually every real project. The harm is those commits becoming release copy, and excluding them prevents that precisely.

This rule is kept identical to /patch-notes' on purpose — the two read the same history for different audiences, and they must not disagree about whose history it is. Change both together.

The genuine wrong-history signal is different: Game commits naming a product that design/ and the code root (src/, Assets/ or Source/) never mention. If you see that, stop.

If no commit in the range is this game's, say so and stop:

"The git history in this repo does not appear to belong to [game]: 0 of the [N] recent commits are Game commits. The recent commits describe [what they actually describe]. I cannot generate a changelog from it — point me at the right history, or supply the change list directly."

Verdict: BLOCKED — stop here without generating a changelog.

Why this is a hard stop, not a warning. Framework-internal commits rendered as player copy read as real changes: a session-hook timeout becomes "Fixed an issue where progress from your last session could be lost on launch" in a game with no save system. That copy is fluent, plausible, and entirely false. A reader cannot tell the difference; only this check can.

Do not treat the preamble's existence as evidence. Injected output means the command ran, never that its subject is your game.


Both blocks are resolved before this skill runs. Use them as the starting point for Phase 2 rather than re-running the same commands.


Phase 1: Parse Arguments

Read the argument for the target version or sprint number. If a version is given, use the corresponding git tag. If a sprint number is given, use the sprint date range.

Verify the repository is initialized: run git rev-parse --is-inside-work-tree to confirm git is available. If not a git repo, inform the user and abort gracefully.

If there is no history to read — not a git repository, or no commits yet:

"No git history found. A changelog is built from commits — commit the work first, or supply the change list directly."

Verdict: BLOCKED — stop here without generating a changelog.


Phase 2: Gather Change Data

Read the git log since the last tag or release:

git log --oneline [last-tag]..HEAD

If no tags exist, bound the range explicitly — git log --oneline -n 100. Do not fall back to the full log: on an established repo that is thousands of lines for a changelog covering one release, and the oldest of them are the least relevant. If 100 commits does not reach far enough back, say so and ask for a start ref rather than widening blindly.

Read sprint reports from production/sprints/ for the relevant period to understand planned work and context behind changes.

Read completed design documents from design/gdd/ for any new features implemented during this period. Read them by section: find the headings you need with the Grep tool (pattern ^#, content mode) and Read those ranges with offset and limit.


Phase 3: Categorize Changes

Categorize every change into one of these categories:

  • New Features: Entirely new gameplay systems, modes, or content
  • Improvements: Enhancements to existing features, UX improvements, performance gains
  • Bug Fixes: Corrections to broken behavior
  • Balance Changes: Tuning of gameplay values, difficulty, economy
  • Technical Debt / Refactoring: Refactors and cleanup of the game's code that change nothing the player sees — a commit that says it refactors, cleans up or tidies, and names no fix, feature or tuning. Internal changelog only; never in the player-facing one
  • Known Issues: Issues the team is aware of but have not yet resolved
  • Miscellaneous: Changes that do not fit the above categories, or commits whose messages are too vague to classify confidently

For each commit, check whether the message contains a task ID or story reference (e.g. [STORY-123], TR-, #NNN, or similar). Count commits that lack any task reference and include this count in the Phase 4 Metrics section as: Commits without task reference: [N].


Phase 4: Generate Internal Changelog

# Internal Changelog: [Version]
Date: [Date]
Sprint(s): [Sprint numbers covered]
Commits: [Count] ([first-hash]..[last-hash])

## New Features
- [Feature Name] -- [Technical description, affected systems]
  - Commits: [hash1], [hash2]
  - Owner: [who implemented it]
  - Design doc: [link if applicable]

## Improvements
- [Improvement] -- [What changed technically and why]
  - Commits: [hashes]
  - Owner: [who]

## Bug Fixes
- [BUG-ID] [Description of bug and root cause]
  - Fix: [What was changed]
  - Commits: [hashes]
  - Owner: [who]

## Balance Changes
- [What was tuned] -- [Old value -> New value] -- [Design intent]
  - Owner: [who]

## Technical Debt / Refactoring
- [What was cleaned up and why]
  - Commits: [hashes]

## Miscellaneous
- [Change that didn't fit other categories, or vague commit message]
  - Commits: [hashes]

## Known Issues
- [Issue description] -- [Severity] -- [ETA for fix if known]

## Metrics
- Total commits: [N]
- Files changed: [N]
- Lines added: [N]
- Lines removed: [N]
- Commits without task reference: [N]

Phase 5: Generate Player-Facing Changelog

# What is New in [Version]

## New Features
- **[Feature Name]**: [Player-friendly description of what they can now do
  and why it is exciting. Focus on the experience, not the implementation.]

## Improvements
- **[What improved]**: [How this makes the game better for the player.
  Be specific but avoid jargon.]

## Bug Fixes
- Fixed an issue where [describe what the player experienced, not what was
  wrong in the code]
- Fixed [player-visible symptom]

## Balance Changes
- [What changed in player-understandable terms and the design intent.
  Example: "Healing potions now restore 50 HP (up from 30) -- we felt
  players needed more recovery options in late-game encounters."]

## Known Issues
- We are aware of [issue description in player terms] and are working on a
  fix. [Workaround if one exists.]

---
Thank you for playing! Your feedback helps us make the game better.
Report issues at [link].

Phase 6: Output

Output both changelogs to the user. The internal changelog is the primary working document. The player-facing changelog is ready for community posting after review.


Phase 7: Offer File Write

After presenting the changelogs, ask the user:

"May I write this changelog to docs/CHANGELOG.md? [A] Yes, append this entry (recommended if the file already exists) [B] Yes, overwrite the file entirely [C] No — I'll copy it manually"

  • Check whether docs/CHANGELOG.md exists before asking. If it does, default the recommendation to [A] append.
  • If the user selects [A]: append the new internal changelog entry to the top of the existing file (newest entries first).
  • If the user selects [B]: overwrite the file with the new changelog.
  • If the user selects [C]: stop here without writing.

After a successful write: Verdict: CHANGELOG WRITTEN — changelog saved to docs/CHANGELOG.md. If the user declines: Verdict: COMPLETE — changelog generated.


Phase 7: Next Steps

  • Use /patch-notes [version] to generate a styled, saved version for public release.
  • Use /release-checklist before publishing the changelog externally.

Guidelines

  • Never expose internal code references, file paths, or developer names in the player-facing changelog
  • Group related changes together rather than listing individual commits
  • If a commit message is unclear, check the associated files and sprint data for context
  • Balance changes should always include the design reasoning, not just the numbers
  • Known issues should be honest — players appreciate transparency
  • If the git history is messy (merge commits, reverts, fixup commits), clean up the narrative rather than listing every commit literally

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.