Commit Message Storyteller
- 218 installs
- 2 repo stars
- Updated July 24, 2026
- ilteoood/harness
Turn messy git diffs into conventional, reviewer-friendly commit messages with a clear narrative body.
About
Commit-message-storyteller is a journey-wide agent skill that helps solo builders write Conventional Commits with bodies that explain motivation, user impact, and risk—not just what files changed. It packages the standard type(scope): description shape plus optional narrative body and footers so changelogs, semantic release tooling, and human reviewers parse history quickly. Examples cover feat, fix, refactor, perf, and docs with realistic scopes like payments, api, and dashboard, showing how to state the bug symptom, the fix, and linked issues. Because every meaningful git commit benefits from the same discipline, the skill applies across Build, Ship, and Operate whenever you stage work, not only at PR time. It is aimed at indie developers who ship alone but still want audit-friendly history and fewer “what does this commit do?” threads. Invoke it after implementing a change set and before git commit or when squashing a branch for merge.
- Conventional Commits v1.0.0 format with type, scope, description, body, and footers
- Worked examples for feat, fix, refactor, perf, and docs with business context in the body
- Issue linkage patterns such as Closes # and Fixes # in footers
- Encourages why-and-impact prose instead of bullet dumps of file names
- Quick reference aligned to conventionalcommits.org for consistent team history
Commit Message Storyteller by the numbers
- 218 all-time installs (skills.sh)
- +30 installs in the week ending Jul 25, 2026 (Skillselion tracking)
- Ranked #167 of 739 Git & Pull Requests skills by installs in the Skillselion catalog
- Security screen: LOW risk (skills.sh audit)
- Data as of Jul 25, 2026 (Skillselion catalog sync)
npx skills add https://github.com/ilteoood/harness --skill commit-message-storytellerAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 218 |
|---|---|
| repo stars | ★ 2 |
| Security audit | 3 / 3 scanners passed |
| Last updated | July 24, 2026 |
| Repository | ilteoood/harness ↗ |
What it does
Turn messy git diffs into conventional, reviewer-friendly commit messages with a clear narrative body.
Files
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:
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 |
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 #312Story 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 diffSee references/conventional-commits-guide.md for type examples and scope guidelines.
Conventional Commits — Quick Reference Guide
Full spec: https://www.conventionalcommits.org/en/v1.0.0/
---
Format
<type>(<scope>): <description>
[optional body]
[optional footer(s)]---
Type Examples
feat — New Feature
feat(payments): add Apple Pay support for checkout flow
Users in supported regions can now complete purchases using Apple Pay.
This reduces checkout friction and is expected to improve mobile conversion rates.
Closes #88fix — Bug Fix
fix(api): correct off-by-one error in pagination offset
The results page was skipping the last item on every page because the
offset calculation used `>` instead of `>=`. Users were missing records
silently with no error.
Fixes #201refactor — Code Restructure (no behavior change)
refactor(user-service): extract email validation into shared utility
Email validation logic was duplicated across 4 modules. Extracted into
`utils/validators.ts` so future changes only need to happen in one place.perf — Performance Improvement
perf(dashboard): lazy-load chart components to reduce initial bundle size
The dashboard was importing all chart types upfront, adding ~180KB to the
initial load. Charts are now loaded on demand, cutting initial load time
by ~40% on slow connections.docs — Documentation Only
docs(readme): add local development setup instructions
New contributors were struggling to get the dev environment running.
Added step-by-step instructions covering Node version, env vars, and
the database seed command.test — Tests Added or Updated
test(auth): add coverage for concurrent login edge cases
The login flow had no tests for simultaneous requests from the same
session. Added tests that verify only one session token is issued
when multiple requests arrive in the same tick.chore — Maintenance / Config
chore(deps): upgrade eslint from v8 to v9
v8 reached end-of-life. Migrated config to flat config format required
by v9. No rule changes — this is a tooling-only update.ci — CI/CD Pipeline
ci: add caching for node_modules in GitHub Actions
Cold CI runs were taking 4+ minutes due to repeated installs.
Adding cache restore on lockfile hash reduces this to ~90 seconds.revert — Reverting a Commit
revert: feat(notifications): add push notification opt-in
Reverts commit a3f92bc.
The push notification feature caused a crash on Android 12 devices.
Rolling back until the root cause is identified.---
Scope Guidelines
The scope is optional but strongly recommended. It should be:
- A short noun identifying the area of the codebase:
auth,api,dashboard,payments - Consistent across the project (don't mix
userandusers) - Omitted if the change is truly global
---
Breaking Changes
Add BREAKING CHANGE: in the footer (or use ! after the type):
feat(api)!: remove v1 endpoints
All v1 REST endpoints have been removed following the 6-month deprecation
notice. Consumers must migrate to v2 before upgrading.
BREAKING CHANGE: /api/v1/* routes no longer exist. See migration guide at docs/v2-migration.md---
Body Writing Tips
Ask yourself before writing the body:
- What was broken / missing before this change?
- Why was this approach chosen over alternatives?
- What will be different for users or developers after this?
Avoid:
- Restating what the diff already shows ("changed the variable name")
- Vague language ("various improvements", "miscellaneous fixes")
- Future tense ("this will fix...") — write in present/past tense
---
Commit Message Anti-Patterns
| ❌ Bad | ✅ Better |
|---|---|
fix bug | fix(cart): prevent duplicate items on rapid add-to-cart clicks |
updates | feat(profile): allow users to update display name |
WIP | Don't commit WIP — stash it |
misc changes | Split into separate, meaningful commits |
John's changes | Describe what changed, not who changed it |
Related skills
Caveman CommitGenerate terse, Conventional Commits messages that preserve intent without fluff or AI attribution.264k92.8k
Git Guardrails Claude CodePrevent Claude Code from accidentally running destructive git commands like force push, hard reset, or clean.164k187kResolving Merge ConflictsQuickly understand, resolve, and commit merge conflicts without losing work or breaking their flow.160k187k
Using Git WorktreesGuarantee every new feature or implementation task runs inside a clean, isolated workspace without polluting the main branch or current working directory.145k261k
Git CommitGenerate accurate conventional commit messages and intelligently stage files directly from natural language requests.40.2k37k
Resolve Merge ConflictsQuickly understand and resolve Git merge conflicts without losing context or breaking changes.15.6k147FAQ
Is Commit Message Storyteller safe to install?
skills.sh reports 3 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.