github/commit-message-storyteller
Analyzes git diffs or staged changes and generates narrative commit messages that explain WHY a change was made, not just what changed — following Conventional Commits format. Use when asked to "write a commit message", "generate a commit", "describe my changes", "what should I commit this as", "commit this", "summarize my diff", or "help me commit". Works with git diff output, staged files, or plain descriptions of changes.
npx skills add https://github.com/github/awesome-copilot --skill commit-message-storytellerTransforms 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.
Have at least one of the following ready:
git diff or git diff --stagedAsk the user (or infer from the diff) for:
If the user provides a raw git diff, extract this context automatically from the diff.
Map the change to a Conventional Commits type using this guide:
| Type | Use When |
|------|----------|
| feat | A new feature or capability is added |
| fix | A bug or incorrect behavior is corrected |
| refactor | Code restructured without changing behavior |
| perf | A change that improves performance |
| docs | Documentation only changes |
| style | Formatting, whitespace, missing semicolons (no logic change) |
| test | Adding or updating tests |
| chore | Build process, dependency updates, config changes |
| ci | CI/CD pipeline changes |
| revert | Reverting a previous commit |
See references/conventional-commits-guide.md for detailed examples.
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>
Subject line (first line):
Body (the story):
Footer:
Closes #123, Fixes #456, Refs #789BREAKING CHANGE: <description>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.
If the diff contains logically separate changes, split them into multiple commit messages and tell the user. Use this heuristic:
| Situation | How to Handle |
|-----------|---------------|
| User provides no context beyond a diff | Infer type and scope from file names and changed symbols |
| Changes span many files with no clear theme | Ask: "Is this one logical change, or multiple?" |
| Breaking change detected | Add BREAKING CHANGE: footer automatically |
| User says "keep it short" | Omit body, just write a strong subject line |
| No issue number available | Omit the footer entirely |
# 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.
Take github/commit-message-storyteller from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.