--- name: git-commit description: > Commit changes with clean, structured messages. Use when the user says "commit", "save my work", "commit changes", or invokes /git-commit. Enforces conventional commit format, groups changes into logical commits, and maintains CHANGELOG.md. Never squash unrelated changes into one commit. user-invocable: true allowed-tools: Bash, Read, Grep, Glob, Write, Edit --- # Commit Skill ## Workflow 1. Run `git status` and `git diff --stat` to assess all pending changes. 2. **Triage: session vs pre-existing.** Separate changes you made in this session from changes that were already dirty when the session started. Check the conversation history — if you didn't touch a file, it's pre-existing. After grouping your own commits, surface any remaining modified or untracked files to the user: > These files are also modified/untracked but weren't part of this > session's work: > - `path/to/file` — > - `path/to/other` — > > Should any of these be included in a commit? Wait for the user's answer before staging them. Never silently skip or silently include pre-existing changes. 3. Group changes into **logical commits** — each commit should represent one coherent change. Common groupings: - A bug fix (all files touched to fix one issue) - A new feature or system (e.g., new trait files + localization + events) - Refactoring / cleanup (encoding fixes, comment fixes, renaming) - Config / meta changes (CLAUDE.md, .claude/ skills, mod descriptor) - Data corrections (province remapping, missing fields) 4. For each logical group, stage only the relevant files and commit with a properly formatted message. 5. After all commits, update CHANGELOG.md. ## Commit Message Format ``` (): Co-Authored-By: Claude ``` The trailer is intentionally **unpinned** — do not write a model version into the example. The model-identifier variant the Claude Code harness appends automatically (e.g. `Co-Authored-By: Claude Opus `) is equally valid; leave it as the harness emits it. Pinned version numbers are the root cause of attribution drift (this line read `Claude Opus 4.6` for months after the model moved on). ### Types | Type | Use for | |------|---------| | `feat` | New game system, mechanic, or feature | | `fix` | Bug fix — crashes, logic errors, broken references | | `refactor` | Code restructuring without behavior change | | `chore` | Build, config, tooling, skills, CLAUDE.md, infrastructure | | `docs` | Documentation, design docs, discussion logs, briefings | | `data` | Game data changes — entity definitions, map templates, balance values | | `loc` | Localization additions or corrections | ### Scope Use the project subsystem as scope. Examples: - `agents` — agent personality files (.claude/agents/) - `skills` — skill definitions (.claude/skills/) - `docs` — design documents, architecture docs - `briefings` — agent briefing files (docs/briefings/) - `discussions` — discussion round archives - `schema` — database schema changes - `db` — database operations, connector scripts - `config` — project configuration, endpoints - `simulation` — game simulation server-side code - `client` — game client code, rendering - `engine` — engine-level systems (ECS, chunk loading, etc.) - `ui` — user interface, HUD, insert/minimap - `audio` — sound system, audio propagation - `assets` — visual assets, sprites, art - `meta` — project config, CLAUDE.md, team roster ### Rules - Summary line: imperative mood, lowercase, no period, max 72 chars. - Body: wrap at 72 chars. Explain *why* the change was made. - Never combine unrelated changes (e.g., don't mix a crash fix with new features). - When in doubt, prefer more smaller commits over fewer large ones. ### Clerk safety valve (`Clerk-Skip:` trailer) The pre-push clerk reviews each commit for D-record consistency. For a pure bulk content commit — e.g. shipping thousands of generated planetary description files — that review is moot and just burns agents on noise. Add a `Clerk-Skip:` **trailer line** to the commit message and `reach dev clerk` auto-approves that commit without spawning an agent. Use it only for content/data dumps, never for commits that touch `governance/`, code, or ticket-bearing work. It must be a trailer (a line starting with `Clerk-Skip:`), not inline prose — that way a commit that merely *mentions* the token in its subject or body isn't skipped. ``` data(content): generate 5000 planetary description files Clerk-Skip: bulk generated content, no D-record surface ``` ### Examples ``` feat(simulation): add LOS shadowcasting for vision cone Implements 2D shadowcasting per z-level with forward/peripheral/ blind spot zones per D-011 and D-015 specifications. ``` ``` docs(discussions): archive round 13 engine selection debate Split completed round from DISCUSSION.md into per-round archive. Updated briefings for Tyre and Troblum with new requirements. ``` ``` chore(agents): add Stig UI developer agent Standby agent for UI implementation phase. Configured with briefing reference and Settled Reach-themed personality. ``` ## CHANGELOG.md Format Maintain `CHANGELOG.md` in the project root. Use Keep a Changelog format: ```markdown # Changelog ## [Unreleased] ### Added - New feature descriptions ### Fixed - Bug fix descriptions ### Changed - Change descriptions ``` Group entries under: Added, Fixed, Changed, Removed. Write entries from the player/modder perspective, not implementation details. After committing, read the existing CHANGELOG.md (create if missing), prepend new entries under `[Unreleased]`, and commit the changelog update separately as: ``` chore(meta): update changelog ``` ## Version Tracking Version is tracked in CHANGELOG.md. When the user bumps the version, move `[Unreleased]` entries under a new version heading and commit as: ``` chore(meta): release v0.1.0 ``` ## Staging Rules See `.claude/rules/git-safety.md` for staging rules (always-loaded). These apply to ALL git operations, not just this skill.