SKILL 04 / CODING · DEEP DIVE

Git Workflow Skills

Commit / PR / changelog — the diff only answers "what changed"

2026-09-05 · BigCat

This is the most-installed category of skill, and the most overrated one. The diff records what you changed. It has never recorded why.

Prerequisite → Skill 03 Code Review Skills (review first, then the shipping half)

// WHY THIS MATTERS

Your agent wrote the code and something reviewed it. What follows is the part nobody enjoys: squeezing out a commit message, writing the PR description, trawling two hundred commits at release time to assemble a changelog. That is exactly what this category kills. This issue names nine real, installable or readable items with installs and a "when not to install it" for each. The criteria come in the second half, because in this category the important judgment is a single one: which of these jobs belongs to a skill, and which one actually belongs nailed into a git hook.

// 01

What it kills for you: nine installables, table first

Claim: these nine split into three stages — before the commit (writing the message), after it (the PR pile), and at release time (the changelog). Pick one per stage; stacking across stages is fine.
Item (name per the repo directory) Kills this chore When not to install ────────────────────────────────────────────────────────────────────────────────────── git-commit-helper (davila7) staring at a diff for words no commit convention yet git-pushing (davila7) add / commit / push by hand you stage selectively gh-address-comments (davila7) tabbing between PR and editor only one or two comments gh-fix-ci (davila7) digging through Actions logs the red is obvious to you github-pr-review (aidankinzett) a review posted unread you don't review on GitHub finishing-a-development-branch (superpowers) the "now what?" stall single trunk, direct push using-git-worktrees (superpowers) stash-and-switch churn you never work in parallel changelog-generator (Composio / davila7) reading 200 commits at release release-please already runs built-in create a pr / --from-pr (official) hand-writing PR descriptions — ────────────────────────────────────────────────────────────────────────────────────── No star counts this issue: the numbers scraped off GitHub pages were visibly wrong in several cases

Installs (all copy-pasteable as written)

# 1) Built in, nothing to install (per Claude Code · Common workflows, 2026-09)
create a pr                      # the docs' own wording — just say this
claude --from-pr 1234            # reopen the session that created that PR
claude --worktree feature-auth   # a parallel session that won't collide

# 2) superpowers (ships finishing-a-development-branch, using-git-worktrees)
/plugin install superpowers@claude-plugins-official

# 3) aidankinzett's PR review skill
/plugin marketplace add aidankinzett/claude-git-pr-skill

# 4) davila7's CLI, interactive component picker (agent / command / hook / mcp / skill)
npx claude-code-templates@latest
# The crudest and most portable route: copy the SKILL.md folder into ~/.claude/skills/

The first thing you can run right now, with nothing installed — this pipe is straight out of the official docs:

git log --oneline -20 | claude -p "summarize these recent commits"

Swap the second half for "group by feature / fix / breaking and write user-facing release notes" and you already have a changelog generator. Run that first, then decide whether the skill is worth installing.

Failure mode: installing all nine. Their descriptions compete for the same triggers — say "push this" and git-pushing may fire when all you wanted was to look at the diff. One per stage.
// 02

Mechanism: the diff is the only input, and that sets the ceiling

Claim: every skill in this category eats exactly one thing — git diff --staged. A diff is a complete record of the what and a blank page for the why. That asymmetry explains everything these tools do well and everything they get wrong.

The half the diff can answer

git-commit-helper (SKILL.md) is typical: it reads git diff --staged and git status, then emits <type>(<scope>): <description> with type restricted to feat / fix / docs / style / refactor / test / chore, a summary under 50 characters, imperative mood, no trailing period — and it nudges you toward git add -p when unrelated changes are staged together. The diff holds all of that: type from which files moved, scope from the directory, splittability from how many clusters the change forms. This half it does more consistently than a human, because a human writes "update".

The half that isn't in there

The same SKILL.md also asks the body to "explain reasoning, not merely actions". Reasoning is not in the diff. The model can only infer motive from code, and what it infers is usually the what restated. That is the one real failure mode of this category.

Actionable corollary: the right moment for a commit skill is immediately after the work, in the session that still holds the conversation. The why is in context right then; a day later only the diff remains. "Batch up a week and write the messages later" is the least useful way to use these tools.

Every step downstream loses information

Changelog tools don't eat the diff — they eat the commit messages. changelog-generator (the same file appears in Composio's collection and in davila7's) does six things: scan history over a date range or tag span, categorize, translate developer wording into user wording, format, filter out internal commits such as refactors and test changes, and apply a brand voice. Its ceiling is pinned by the quality of your commits.

diff ──→ commit message ──→ changelog ↑ ↑ ↑ what: complete why: only if you only what survived wrote it down in the message Each hop drops information, and what drops cannot be recovered

This is where Conventional Commits actually earns its keep: feat: / fix: / BREAKING CHANGE are not tidiness, they are structured metadata you leave for downstream machines at the moment of commit. Leave it and the changelog and the version number can be computed. Skip it and everything downstream is guessing.

// 03

Real usage and limits: encode conventions as examples, nail risky steps into scripts

Claim: whether one of these is usable comes down to two things — is your team's actual convention encoded in it, and does the irreversible step get handed back to a human.

Encoding the convention: paste examples, don't write clauses

Everyone can recite plain Conventional Commits. What nobody can recite is your repo's real convention: whether scope is the package or the module, how big a change has to be before it counts as a feat, whether the issue number goes in the footer. The cheapest fix is to open the last twenty commits your team is happy with, pick three to five, and paste them whole into SKILL.md as examples — three real "diff looked like this → message reads like this" pairs beat ten rules (Skill 18 takes this recipe apart on its own). Where to put it: .claude/skills/ in the repo when the team shares it, ~/.claude/skills/ when it is your own taste.

The PR pile: good skills say what they do not cover

Hand the irreversible step back

Superpowers' finishing-a-development-branch (SKILL.md) is the one worth copying. It runs the full test suite first and halts on failure without even showing the menu; detects whether you are in a normal repo or a worktree; confirms the base branch, asking "this branch split from X — is that correct?" when unsure; and then offers exactly three options: merge back locally / push and open a PR / leave it as-is. Then it waits for a person. The SKILL.md states the reason outright: integration decisions belong to the human. Deletion is stricter still — you must type the word "discard".

The other route is nailing the action into a script. git-pushing (SKILL.md) requires everything to go through its bundled scripts/smart_commit.sh, in its own words: "ALWAYS use the script — do NOT use manual git commands." Deterministic steps into the script, the model only fills in the message — that structure is worth copying into anything that pushes.

Failure mode: letting an agent run commit → push → open PR without a stop. Push is the irreversible surface; once it lands on a shared branch, undoing it is no longer only your problem.
// 04

Costs and alternatives: when a hook beats a skill

Claim: anything with a determinate answer goes to a hook; only judgment goes to a skill. The share of a git workflow that a deterministic tool can simply take over is much larger than this category's marketing suggests.

Why hooks are more reliable: a skill advises, a hook refuses

A skill injects instructions. The model can ignore them, can fail to trigger on them, can follow them today and not tomorrow. A hook is code that runs unconditionally on an event. The Claude Code hooks docs put the relationship plainly: "The hook can deny the call, but staying silent doesn't approve it." A PreToolUse matcher that blocks git push --force is far sturdier than writing "never force-push" ten times in a SKILL.md.

Three jobs that belong to deterministic tools

  1. Format compliance → commitlint (MIT). npm install --save-dev @commitlint/cli, then wire it into husky's commit-msg hook per the project's local-setup guide. Kills: catching format problems in review. When not to: your team hasn't agreed on a convention yet — agree first, tool second.
  2. Changelog and version numbers → git-cliff (dual Apache-2.0 / MIT, cargo install git-cliff, also distributed via npm / PyPI / Docker) or release-please (Apache-2.0; the README recommends the release-please-action). The latter keeps a release PR that stays current as commits land; merging it tags and publishes the release. When not to: your history doesn't follow Conventional Commits — both parse commits, so garbage in, garbage out.
  3. Fixed pre-commit checks → one pre-commit hook. davila7's CLI ships one ready to go: npx claude-code-templates@latest --hook git/pre-commit-validation --yes.

So what's left for a skill

Exactly what a hook cannot do: the why line in the commit body, splitting a tangled change into separate commits, and the "which paths should a reviewer exercise" part of a PR description. All three need judgment and none has an objective oracle. That is this category's real territory; everything else should sink down a layer.

Three bills

// ONE-PAGE BUYING CARD

Install these three first: ① nothing at all — run git log --oneline -20 | claude -p "group by feature/fix/breaking and write release notes", an official pipe you can try today; ② commitlint on husky's commit-msg hook, nailing down the one part that has a determinate answer — it is a hook, not a skill, and that is precisely why it holds; ③ superpowers' finishing-a-development-branch (/plugin install superpowers@claude-plugins-official), which cures the "now what?" stall and hands the irreversible step back to you.

Then add one (one, not all): want consistent commit messages → git-commit-helper, and paste three of your own commits into it the moment you install; reviewing PRs on GitHub → github-pr-review; CI keeps going red → gh-fix-ci; shipping a real release changelog → release-please or git-cliff, not a skill.

When not to install any of this: a solo repo where git commit -m is fine · release-please or changesets already running · a team that doesn't read commit messages at all (fix that first).

Review after two weeks: what share of its commit messages did you ship verbatim? Under half means go add examples, not switch tools.

// GLOSSARY

Conventional Commits
The <type>(<scope>): <description> commit format. The point is not neatness — it is structured metadata for downstream machines, which is how version numbers and changelogs get computed.
commit-msg hook
The local git hook that fires after the message is written and before the commit lands. It can reject the commit, which makes it the only place a format convention actually holds.
release PR
Release-please's core mechanism: a long-lived PR that keeps updating the version bump and CHANGELOG as commits land. Merging it is the release.
worktree
A second independent checkout of the same repository, each on its own branch. Run parallel sessions in them and the edits never collide — no stash churn.
pending review
GitHub's mechanism for batching comments into a draft submitted all at once. github-pr-review uses it as the "a person looks before it ships" gate.
what vs why
A diff fully answers what changed and contains nothing about why. Everything reliable and unreliable about this category follows from that asymmetry.

// FURTHER READING