Index of every page on this site: llms.txt
All skills
github avatar

/commit-message-storyteller

@f10fdb8 official
by githubgithub/awesome-copilot41k stars
5,399
Run it yourself

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", "describe my changes", "what should I commit this as", or "summarize my diff". Works with git diff output, staged files, or plain descriptions of changes. Does not run git commit; to stage files and make the commit, use the git-commit skill.

Use this Skill: https://skilld.dev/gh/github/awesome-copilot/commit-message-storyteller

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈123 tokens for metadata: the name and description. ≈1.2k when used: this file. ≈1k more on demand in 1 file.

Description uses 6.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈490 characters, or 6.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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:

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
build Build system or dependency changes
chore Other maintenance that does not change source or tests
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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts28d3 checks · Risk SAFE
  • Gen Agent Trust Hub28d

    This skill is a text-processing utility designed to help users generate Conventional Commit messages from git diffs. It does not execute code, access the network, or interact with sensitive system resources.

  • Socket28d

    No alerts

  • Snyk28d

    Risk: LOW · No issues

Signed by skilld at f10fdb8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last month
  • Git/VCS
  • commit-messages
  • conventional-commits
  • diff
  • workflow

README badge

README badge for github/awesome-copilot/commit-message-storyteller

Analyzes git diffs or staged changes and generates narrative commit messages following Conventional Commits format, emphasizing why a change was made rather than just what changed. Guides you through identifying commit type, crafting an imperative subject line, and writing a body that explains the problem solved and context.

Generated from the current SKILL.md.

Does this skill work with any git workflow, or just certain branching strategies?
It works with any git workflow. The skill analyzes diffs and generates Conventional Commits messages regardless of whether you're using Git Flow, trunk-based development, or any other strategy.
What if my changes don't fit neatly into one of the Conventional Commits types?
The skill provides a mapping table of ten types (feat, fix, refactor, perf, docs, style, test, chore, ci, revert) that cover the vast majority of real changes. If your change spans multiple types, the skill will ask you to clarify or suggest splitting it into separate commits.
Can I use this if I only have a description of changes, not an actual git diff?
Yes. The skill accepts a plain description of what changed and why, and will generate a commit message without requiring `git diff` output.
Does this enforce breaking change notation automatically?
The skill detects breaking changes from the diff context and will add a `BREAKING CHANGE:` footer automatically if one is identified.
What happens if I don't have an issue number to reference in the footer?
You can omit the footer entirely. Issue references are optional — the skill only includes them if relevant context is available.

Generated from the current SKILL.md. These answers refresh after source changes.