---
name: commit-message-pro
description: "AI commit messages that read like a senior engineer wrote them — Conventional Commits, why-not-what focus. Reads the staged diff and writes a Conventional-Commits-formatted message that explains the WHY, not the what. Detects scope automatically, follows the repo's existing style, and skips 'update file' garbage."
license: MIT
---

# Commit Message Pro

Commit Message Pro reads your staged diff and drafts a Conventional Commits message that explains *why* a change was made, not just which lines moved. It's built for engineers who care about a readable `git log` — people doing code archaeology six months later, reviewers scanning history, and teams that gate CI on commit format. No more `fix stuff` or `update file.ts`.

## When to use it

- You've staged a change and want a clear, conventional subject + body without hand-writing it.
- Your repo enforces Conventional Commits (commitlint, semantic-release, release-please) and you want messages that pass on the first try.
- You're squashing a messy branch and need one coherent message describing the net intent.
- A diff touches several files and you want the scope inferred instead of guessing.

## How it works

The skill operates on what's in the **index** — it runs `git diff --staged` (equivalently `git diff --cached`) and never invents context from unstaged work. From that diff it:

- Picks a **type** (`feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `chore`, `build`, `ci`) by reading what the code actually does.
- Infers **scope** from the dominant changed path or module (e.g. `auth`, `api`, `parser`).
- Mirrors your repo's existing conventions by sampling recent `git log` — subject casing, whether you use scopes, body wrapping, emoji or not.
- Writes a body focused on motivation and tradeoffs, and appends `BREAKING CHANGE:` footers when it detects an incompatible API or signature change.

## Usage

```bash
curl -fsSL --create-dirs -o ~/.claude/skills/commit-message-pro/SKILL.md https://claudeskil.com/skills/commit-message-pro/SKILL.md

git add src/auth/session.ts
# ask Claude: "write a commit message for my staged changes"
```

Produces something like:

```
fix(auth): expire sessions on password change

Stale sessions remained valid after a reset, leaving a window where a
compromised credential still worked. Invalidate all sessions tied to the
user when the password hash changes.
```

## Tips & gotchas

- **Stage first.** Nothing in your index means nothing to summarize — the skill won't read unstaged or untracked files.
- Use `git add -p` to stage only the hunks belonging to one logical change; the message quality tracks directly with how focused the staged diff is.
- If your subject must stay ≤50 chars or your body wrap at 72, say so once — it follows the constraint and reuses it.
- For breaking changes, keep the relevant signature change staged so the `BREAKING CHANGE:` footer is generated rather than guessed.

## FAQ

**Does it commit for me?**
No. It generates the message text. You review and run `git commit` (or paste it into your editor). Nothing is committed without you.

**Will it match a custom commitlint config?**
It follows Conventional Commits and your observed history. For unusual custom types or scope-enums, mention the rule and it adapts the output to satisfy it.

**Can it handle a huge multi-file diff?**
Yes, but the message generalizes across everything staged. For unrelated changes, stage and message them separately for sharper history.