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
Install / Use
npx skills add github/awesome-copilot --skill commit-message-storytellerInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of commit-message-storyteller
commit-message-storyteller scores 91/100 on our quality scale, 457th of 2,860 Development & Engineering skills we index (top 16%).
Its SKILL.md is 5.0 KB long, well organised into 14 sections with 3 code examples: a solid amount of guidance for an agent.
With 39,348 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated 3 days ago, so commit-message-storyteller is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
commit-message-storyteller compared with similar skills
All 4 of these similar skills score higher than commit-message-storyteller; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| commit-message-storyteller (this skill)by github | 91 | 39.3k | 3d ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 85.7k | 12d ago | CLAUDE.md |
| ai-job-searchby MadsLorentzen | 100 | 44.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 41.7k | 1d ago | CLAUDE.md |
| algorithmic-artby anthropics | 100 | 177.9k | 5d ago | SKILL.md |
Frequently asked questions
- How do I install commit-message-storyteller?
- Run
npx skills add github/awesome-copilot --skill commit-message-storyteller. The install tabs above show the steps for each supported agent. - Which AI agents does commit-message-storyteller work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is commit-message-storyteller safe to use?
- It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is commit-message-storyteller still maintained?
- The repository was last updated 3 days ago, so commit-message-storyteller is actively maintained.
Skill content
View source on GitHubname: commit-message-storyteller description: '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.'
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", "help me commit", or "generate a commit"
- 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 difforgit 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:
- What changed — files, functions, logic affected
- Why it changed — bug fix, new feature, refactor, performance, etc.
- 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:
| 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.
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
| 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 |
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.
Related Skills
Agent-Reach
85.7kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ai-job-search
44.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
41.7kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.