Commit Message Storyteller

Commit Message Storyteller

Transforms raw git diffs and change descriptions into clear, story-driven commit messages that follow the Conventional Commits specification. Instead of "update file.js", you get messages that communicate intent, context, and impact.

When to Use This Skill

• User says "write a commit message"

• User pastes a git diff or describes code changes

• User says "what should I commit this as?" or "summarize my diff"

• User wants better commit history for their team or open-source project

• User is preparing a pull request and wants meaningful commit messages

Prerequisites

Have at least one of the following ready:

• Output from git diff or git diff --staged

• A description of what you changed and why

• A list of modified files

How It Works

Step 1: Gather the Change Context

Ask the user (or infer from the diff) for:

1. What changed — files, functions, logic affected

2. Why it changed — bug fix, new feature, refactor, performance, etc.

3. Who/what triggered it — issue number, user request, tech debt, etc.

If the user provides a raw git diff, extract this context automatically from the diff.

Step 2: Identify the Commit Type

Map the change to a Conventional Commits type using this guide:

See references/conventional-commits-guide.md for detailed examples.

Step 3: Write the Commit Message

Follow this structure:

<type>(<optional scope>): <short imperative summary>

<body — the story: why this change was made, what problem it solves>

<footer — issue refs, breaking change notices>

Rules for Each Part

Subject line (first line):

• Use imperative mood: "add", "fix", "remove" — not "added" or "fixes"

• Max 72 characters

• No period at the end

• Lowercase after the colon

Body (the story):

• Explain the why, not the what (the diff already shows the what)

• Describe the problem that existed before this change

• Mention any alternatives considered if relevant

• Keep lines under 100 characters

• Separate from subject with a blank line

Footer:

• Reference issues: Closes #123, Fixes #456, Refs #789

• Mark breaking changes: BREAKING CHANGE: <description>

Step 4: Generate Output

Produce the commit message in a copyable code block, followed by a one-line plain-English explanation of the story you told.

Example output:

fix(auth): prevent token refresh loop on expired sessions

When a user's session expired mid-request, the auth middleware was
triggering a token refresh, which itself failed validation and triggered
another refresh — causing an infinite retry loop that crashed the app.

This adds a recursion guard flag that aborts the refresh cycle if a
refresh is already in progress, returning a clean 401 instead.

Closes #312

Story told: A silent infinite loop on session expiry was crashing the app; this stops the cycle early and returns a clean error.

Multiple Commits from One Diff

If the diff contains logically separate changes, split them into multiple commit messages and tell the user. Use this heuristic:

• Different files with unrelated purposes → likely separate commits

• Same file but distinct concerns (e.g., bug fix + refactor) → suggest splitting

• Everything tightly coupled → one commit is fine

Edge Cases

Quick Reference

# Get your staged diff to paste into Copilot
git diff --staged

# Or get the last uncommitted working tree changes
git diff

See references/conventional-commits-guide.md for type examples and scope guidelines.