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.
- Installs
- 537
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/ilteoood/harness --skill commit-message-storyteller- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads commit-message-storyteller automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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.
FAQ
What does the commit-message-storyteller skill do?
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.
How do I install commit-message-storyteller?
Run npx skills add https://github.com/ilteoood/harness --skill commit-message-storyteller in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/commit-message-storyteller/ (personal) or .claude/skills/commit-message-storyteller/ (project).
Which AI agents can use commit-message-storyteller?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is commit-message-storyteller safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains commit-message-storyteller?
It is published by ilteoood in ilteoood/harness. It has 537 recorded installs.
More from ilteoood/harness
github-issues
ilteoood/harness
Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, manage repository labels, set issue fields (dates, priority, custom fields), set issue types, manage issue workflows, link issues, add dependencies, or track blocked-by/blocking relationships. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", "set the priority", "set the start date", "create a label", "rename a label", "list repo labels", "link issues", "add dependency", "blocked by", "blocking", or any GitHub issue management task.
git-commit
ilteoood/harness
Execute git commit with conventional commit message analysis, intelligent staging, and message generation. Use when user asks to commit changes, create a git commit, or mentions "/commit". Supports: (1) Auto-detecting type and scope from changes, (2) Generating conventional commit messages from diff, (3) Interactive commit with optional type/scope/description overrides, (4) Intelligent file staging for logical grouping
conventional-commit
ilteoood/harness
Prompt and workflow for generating conventional commit messages using a structured XML format. Guides users to create standardized, descriptive commit messages in line with the Conventional Commits specification, including instructions, examples, and validation.
create-technical-spike
ilteoood/harness
Create time-boxed technical spike documents for researching and resolving critical development decisions before implementation.
codeql
ilteoood/harness
Comprehensive guide for setting up and configuring CodeQL code scanning via GitHub Actions workflows and the CodeQL CLI. This skill should be used when users need help with code scanning configuration, CodeQL workflow files, CodeQL CLI commands, SARIF output, security analysis setup, or troubleshooting CodeQL analysis.
create-specification
ilteoood/harness
Create a new specification file for the solution, optimized for Generative AI consumption.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.