Commit-Message-Storyteller
Commit-Message-Storyteller是一款code方向的AI技能，核心价值是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，可用于解决开发者在code领域的实际问题，帮助用户提升效率、自动化重复任务或优化工作流。
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
mkdir -p ./skills/commit-message-storyteller && curl -sfL https://raw.githubusercontent.com/github/awesome-copilot/main/skills/commit-message-storyteller/SKILL.md -o ./skills/commit-message-storyteller/SKILL.mdRun in terminal / PowerShell. Requires curl (Unix) or PowerShell 5+ (Windows).
Skill Content
# Commit Message Storyteller
Transforms raw git diffs and change descriptions into clear, story-driven commit messages that follow the [Conventional Commits](https://www.conventionalcommits.org/) 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 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 |
| `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 |
|-----------|--------
🎯 Best For
- Developers scaffolding new projects
- Prototype builders
- Data analysts
- Business intelligence teams
- Claude users
💡 Use Cases
- Bootstrapping React components
- Creating API route handlers
- Finding patterns in customer data
- Creating automated dashboards
📖 How to Use This Skill
- 1
Install the Skill
Copy the install command from the Terminal tab and run it. The SKILL.md file downloads to your local skills directory.
- 2
Load into Your AI Assistant
Open Claude or GitHub Copilot and reference the skill. Paste the SKILL.md content or use the system prompt tab.
- 3
Apply Commit-Message-Storyteller to Your Work
Open your project in the AI assistant and ask it to apply the skill. Start with a small module to verify the output quality.
- 4
Review and Refine
Review AI suggestions before committing. Run tests, check for regressions, and iterate on the skill output.
❓ Frequently Asked Questions
Can I customize the generated output?
Yes — modify the skill's prompt instructions to match your project conventions and coding style.
Can this connect to my database directly?
Most data skills accept CSV or JSON input. Database connectors are listed in the Works With section.
Is Commit-Message-Storyteller compatible with Cursor and VS Code?
Yes — this skill works with any AI coding assistant including Cursor, VS Code with Copilot, and JetBrains IDEs.
Do I need specific dependencies for Commit-Message-Storyteller?
Check the install command and Works With section. Most code skills only require the AI assistant and your codebase.
How do I install Commit-Message-Storyteller?
Copy the install command from the Terminal tab and run it. The skill downloads to ./skills/commit-message-storyteller/SKILL.md, ready to use.
⚠️ Common Mistakes to Avoid
Using generated code without understanding
Understand what generated code does before shipping it to production.
Not validating data quality
AI analysis is only as good as your input data. Profile and clean data before analysis.
Skipping validation
Always test AI-generated code changes, even for simple refactors.
Missing dependency updates
Check if the skill requires updated dependencies or new packages.