mirror of
https://github.com/github/awesome-copilot.git
synced 2026-05-04 22:25:57 +00:00
feat(skills): add commit-message-storyteller skill (#1516)
* chore: publish from staged * feat(skills): add commit-message-storyteller skill * fix(commit-message-storyteller): correct reference path to bundled guide * chore: remove materialised plugins * fix: move conventional commits guide into references folder * fix: reset README.skills.md to staged base and regenerate with skill entry * Fixing validation --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Aaron Powell <me@aaron-powell.com>
This commit is contained in:
Kweku Dzata
GitHub
@@ -88,6 +88,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
|
||||
| [code-tour](../skills/code-tour/SKILL.md)<br />`gh skills install github/awesome-copilot code-tour` | Use this skill to create CodeTour .tour files — persona-targeted, step-by-step walkthroughs that link to real files and line numbers. Trigger for: "create a tour", "make a code tour", "generate a tour", "onboarding tour", "tour for this PR", "tour for this bug", "RCA tour", "architecture tour", "explain how X works", "vibe check", "PR review tour", "contributor guide", "help someone ramp up", or any request for a structured walkthrough through code. Supports 20 developer personas (new joiner, bug fixer, architect, PR reviewer, vibecoder, security reviewer, and more), all CodeTour step types (file/line, selection, pattern, uri, commands, view), and tour-level fields (ref, isPrimary, nextTour). Works with any repository in any language. | `references/codetour-schema.json`<br />`references/examples.md`<br />`scripts/generate_from_docs.py`<br />`scripts/validate_tour.py` |
|
||||
| [codeql](../skills/codeql/SKILL.md)<br />`gh skills install github/awesome-copilot codeql` | 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. | `references/alert-management.md`<br />`references/cli-commands.md`<br />`references/compiled-languages.md`<br />`references/sarif-output.md`<br />`references/troubleshooting.md`<br />`references/workflow-configuration.md` |
|
||||
| [comment-code-generate-a-tutorial](../skills/comment-code-generate-a-tutorial/SKILL.md)<br />`gh skills install github/awesome-copilot comment-code-generate-a-tutorial` | Transform this Python script into a polished, beginner-friendly project by refactoring the code, adding clear instructional comments, and generating a complete markdown tutorial. | None |
|
||||
| [commit-message-storyteller](../skills/commit-message-storyteller/SKILL.md)<br />`gh skills install github/awesome-copilot 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. | `references/conventional-commits-guide.md` |
|
||||
| [containerize-aspnet-framework](../skills/containerize-aspnet-framework/SKILL.md)<br />`gh skills install github/awesome-copilot containerize-aspnet-framework` | Containerize an ASP.NET .NET Framework project by creating Dockerfile and .dockerfile files customized for the project. | None |
|
||||
| [containerize-aspnetcore](../skills/containerize-aspnetcore/SKILL.md)<br />`gh skills install github/awesome-copilot containerize-aspnetcore` | Containerize an ASP.NET Core project by creating Dockerfile and .dockerfile files customized for the project. | None |
|
||||
| [content-management-systems](../skills/content-management-systems/SKILL.md)<br />`gh skills install github/awesome-copilot content-management-systems` | Workflow for building and modifying content management systems across WordPress, Shopify, Wix, Squarespace, Drupal, WooCommerce, Joomla, HubSpot CMS Hub, Webflow, Adobe Experience Manager, and similar platforms. Use when working on CMS themes, plugins, apps, modules, admin panels, media uploads, content models, editors, markdown pipelines, or static export workflows. | `references/cms-platform-workflows.md` |
|
||||
|
||||
@@ -16,5 +16,7 @@
|
||||
},
|
||||
"repository": "https://github.com/github/awesome-copilot",
|
||||
"license": "MIT",
|
||||
"skills": ["./skills/power-platform-architect/"]
|
||||
"skills": [
|
||||
"./skills/power-platform-architect/"
|
||||
]
|
||||
}
|
||||
|
||||
142
skills/commit-message-storyteller/SKILL.md
Normal file
142
skills/commit-message-storyteller/SKILL.md
Normal file
@@ -0,0 +1,142 @@
|
||||
---
|
||||
name: 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](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 |
|
||||
|-----------|---------------|
|
||||
| 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
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
@@ -0,0 +1,151 @@
|
||||
# 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 #88
|
||||
```
|
||||
|
||||
### `fix` — 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 #201
|
||||
```
|
||||
|
||||
### `refactor` — 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 `user` and `users`)
|
||||
- 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 |
|
||||
Reference in New Issue
Block a user