| name | git-commit-writer |
| description | Guide Codex or Claude Code to write professional, informative Git commit messages following industry best practices. Use this skill when writing commit messages, reviewing proposed commits, helping users improve commit message quality, or handling git, version control, or contribution documentation tasks. |
Git Commit Writer
Overview
This skill enables writing professional Git commit messages that follow industry best practices based on Chris Beams' widely-adopted guidelines. Well-crafted commit messages preserve institutional knowledge, improve code maintainability, and make collaboration more effective in either Codex or Claude Code.
When to Use This Skill
Activate this skill when:
- Writing a new commit message for code changes
- Reviewing or improving an existing commit message
- User asks "how should I write this commit message?"
- User provides a poor commit message and needs help improving it
- User mentions git commit, version control, or commit standards
- User is about to commit code and needs guidance
The Seven Core Rules
Apply these rules to every commit message:
1. Separate subject from body with a blank line
Place one blank line between the subject line and the body text. Git tools rely on this separation.
Fix authentication bug in user login
The bcrypt comparison was using the wrong salt parameter.
This commit corrects the parameter and adds unit tests.
2. Limit the subject line to 50 characters
Keep subjects concise and scannable. GitHub warns beyond 50 characters and truncates at 72.
✅ Good: Add user authentication with JWT tokens
❌ Too long: Add comprehensive user authentication system with JWT tokens and refresh
3. Capitalize the subject line
Start with a capital letter for consistency.
✅ Good: Refactor authentication module
❌ Bad: refactor authentication module
4. Do not end the subject line with a period
Periods waste space in the 50-character limit.
✅ Good: Fix memory leak in sync process
❌ Bad: Fix memory leak in sync process.
5. Use the imperative mood in the subject line
Write commands, not descriptions of what was done.
The golden test: Complete this sentence:
"If applied, this commit will [your subject line]"
✅ Imperative: Fix bug in user login
✅ Test: "If applied, this commit will fix bug in user login"
❌ Past tense: Fixed bug in user login
❌ Test: "If applied, this commit will fixed bug in user login" (grammatically incorrect)
Common imperative forms:
- Fix, Add, Remove, Update, Refactor, Improve
- Merge, Revert, Document, Extract, Consolidate
Avoid:
- Fixed, Added, Removed (past tense)
- Fixes, Adds, Removes (present tense)
- Fixing, Adding, Removing (present participle)
- I fixed, I added (first person)
6. Wrap the body at 72 characters
Hard-wrap body text at 72 characters for proper display in terminals and Git tools.
7. Use the body to explain what and why vs. how
The code shows how something was done. The commit message explains:
- What was changed
- Why it was changed
- What problem was being solved
- Why this solution was chosen
Workflow for Writing Commit Messages
Step 1: Understand the Changes
Before writing the commit message, review what was changed:
- What files were modified?
- What functionality was added, removed, or fixed?
- Is this a single logical change (atomic commit)?
Step 2: Craft the Subject Line
Write a subject line that:
- Completes: "If applied, this commit will [subject]"
- Uses imperative mood (Fix, Add, Remove, Update, etc.)
- Stays under 50 characters
- Starts with a capital letter
- Has no ending period
Subject line patterns:
| Pattern | Example |
|---|
| Fix [issue] in [area] | Fix race condition in cache invalidation |
| Add [feature] to [area] | Add dark mode support to user interface |
| Remove [thing] from [area] | Remove deprecated authentication methods |
| Update [thing] to [state] | Update dependencies to latest versions |
| Refactor [area] for [reason] | Refactor auth logic for maintainability |
| Improve [aspect] of [area] | Improve error messages in validation |
Step 3: Decide If a Body Is Needed
Body is required when:
- The change is not self-explanatory from the subject and diff
- There's important context or reasoning to preserve
- The change fixes a bug with non-obvious root cause
- Trade-offs or alternatives were considered
- The change has side effects or consequences
Body is optional for:
- Simple, obvious changes
- Typo fixes (though consider if body would help)
- Very small refactorings with clear purpose
Step 4: Write the Body (If Needed)
Structure the body to answer:
-
What was the problem or motivation?
- What bug occurred or what was missing?
- What user need is being addressed?
-
Why this solution?
- Why was this approach chosen?
- What alternatives were considered?
-
What are the effects?
- Are there side effects or consequences?
- Does this enable future changes?
-
References
- Link to related issues:
Fixes #123
- Link to PRs:
Related to PR #456
- Link to documentation or discussions
Example template:
[Subject line]
[What was the problem - 1-2 sentences]
[Why this solution - 1-3 sentences explaining the approach]
[Optional: Effects, consequences, or next steps]
Fixes #123
Step 5: Apply Final Checks
Before committing, verify:
Common Scenarios and Examples
Scenario 1: Simple Bug Fix
User request: "I fixed a login bug, what should my commit say?"
Response pattern:
Subject: Fix authentication bug in user login
Body (optional):
The password validation was failing due to incorrect bcrypt
salt parameter. This commit corrects the parameter and adds
unit tests to prevent regression.
Fixes #789
Scenario 2: Feature Addition
User request: "I just added dark mode support"
Response pattern:
Subject: Add dark mode support to user interface
Body:
Implements a dark color theme toggleable in user preferences.
The theme persists across sessions and follows WCAG 2.1
Level AA contrast requirements for accessibility.
Uses CSS custom properties for instant theme switching without
page reload.
Closes #567
Scenario 3: Refactoring
User request: "I cleaned up the authentication code"
Response pattern:
Subject: Extract authentication logic into separate service
Body:
Authentication code was scattered across multiple controllers,
making it difficult to maintain and test. This commit
consolidates all authentication logic into a dedicated
AuthService.
Benefits:
- Single responsibility principle compliance
- Easier unit testing with dependency injection
- Consistent authentication behavior across endpoints
No functional changes to authentication behavior.
Scenario 4: Reviewing a Poor Commit
User provides: "Fixed stuff"
Response pattern:
Suggest improvement:
The commit message "Fixed stuff" is too vague. Consider a more
descriptive subject like:
Fix memory leak in background sync process
And add body text explaining:
- What was the memory leak?
- What was causing it?
- How does this fix address it?
Handling Edge Cases
Multiple Related Changes
If multiple related changes are in one commit:
- List them in the body with bullet points
- Ensure they're logically related (otherwise split commits)
Update authentication system for security
- Add rate limiting to login endpoint
- Implement JWT token refresh mechanism
- Update bcrypt rounds to current best practice
These changes work together to improve authentication security
after the security audit recommendations.
Merge Commits
Git creates these automatically, typically don't need custom messages. If customizing:
Merge branch 'feature/dark-mode' into main
Brings dark mode support with accessibility compliance.
All tests passing and code reviewed.
Reverting Commits
Use git revert which auto-generates messages, but enhance with context:
Revert "Add experimental caching layer"
This reverts commit abc123def456.
The caching layer caused data inconsistencies in production
under high concurrent load. Reverting while we investigate
the race condition issue.
Related to incident #2345
Resources
This skill includes:
references/detailed-guide.md
Comprehensive guide with:
- Detailed explanations of all seven rules
- Extensive examples and anti-patterns
- Common scenarios and edge cases
- Links to authoritative sources
Load this reference when:
- User asks for detailed explanations
- User needs examples of specific patterns
- Helping with complex commit scenarios
- User wants to understand the "why" behind rules
Project-Specific Considerations
When working in specific projects:
- Check for existing commit message conventions in CONTRIBUTING.md or similar files
- Follow established patterns in the project's git history
- Note any project-specific prefixes (e.g.,
feat:, fix:, docs:)
- Respect team decisions that differ from these guidelines (consistency matters more than personal preference)
Anti-Patterns to Avoid
Never accept these commit message patterns:
- ❌ Vague:
Fix stuff, Update code, Changes, WIP
- ❌ Non-imperative:
Fixed bug, Updating code, I added feature
- ❌ Too long subjects: Anything over 72 characters
- ❌ Implementation details in subject:
Change function X to use Y instead of Z
- ❌ Missing context:
Fix bug (which bug? what was broken?)
- ❌ Casual language:
Finally got this working!, asdfasdf
Success Criteria
A well-written commit message should:
- Allow future developers to understand the change without reading the code
- Explain the reasoning and context behind decisions
- Enable quick scanning of git history
- Preserve institutional knowledge
- Make code reviews and debugging easier
