write-commit-message
Guidelines for writing effective git commit messages using conventional commits style
When & Why to Use This Skill
This Claude skill streamlines the software development workflow by enforcing the Conventional Commits standard for git commit messages. It provides a structured framework for categorizing changes (such as feat, fix, and chore), ensuring a clear, concise, and machine-readable version history that improves team collaboration and facilitates automated changelog generation.
Use Cases
- Standardizing Team Workflows: Maintain a consistent and professional git history across distributed teams by following a unified commit message structure.
- Automated Release Management: Enable the use of automated tools to generate changelogs and determine semantic versioning bumps based on structured commit types.
- Enhanced Code Auditing: Improve the efficiency of code reviews and debugging by providing clear context and intent within every commit description.
- Breaking Change Documentation: Systematically flag and document breaking changes using standardized syntax to alert other developers and stakeholders.
| name | write-commit-message |
|---|---|
| description | Use when creating git commits. Defines conventional commit format and message structure guidelines. |
Commit Message Guidelines
Guidelines for writing clear, consistent git commit messages.
Conventional Commits Format
Use the conventional commits style:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Full Format with All Options
<type>[optional scope]!: <description>
[optional body]
[optional footer: value]
[optional footer: value]
Commit Types
- feat: New feature
- fix: Bug fix
- test: Adding or updating tests
- docs: Documentation changes
- refactor: Code refactoring (no functional changes)
- style: Code style changes (formatting, whitespace)
- chore: Maintenance tasks, dependencies
- perf: Performance improvements
- ci: CI/CD configuration changes
- build: Build system changes
Scope (Optional)
Add scope in parentheses to provide additional context:
Breaking Changes
Indicate breaking changes with ! after type/scope:
Description Guidelines
- Use imperative mood ("add feature" not "added feature")
- Start with lowercase
- No period at the end
- Keep under 72 characters
- Be specific and descriptive
Simple One-Line Commits
ALWAYS prefer simple, single-line commits.
DO NOT add a body unless absolutely necessary. Most commits should be a single line.
When to Use Multi-line Commits (Rarely)
Only use a body when the commit requires significant explanation that cannot fit in the description:
- Breaking changes that need migration instructions
- Complex architectural decisions that need justification
- Changes affecting multiple systems that need explanation
The code speaks for itself. Commit messages should be concise.
Footers
Footers provide metadata about the commit.
Breaking Changes
Document breaking changes in footer:
Commit Message Customization
IMPORTANT: Do NOT include AI attribution footers like:
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Keep commit messages clean and focused on the changes themselves.
Before Committing
- Check for remote updates:
git fetch - Review your changes:
git statusandgit diff - Stage relevant files:
git add <files> - Write clear commit message
Commit Frequency
- Commit logical units of work
- Don't commit half-finished features
- Ensure tests pass before committing
- One commit per requirement or bug fix (when practical)
Integration with STDD Workflow
When following the spec-test-driven development workflow:
- After completing a requirement (spec + test + implementation)
- Ensure all tests pass
- Run any precommit hooks
- Commit with descriptive message
- Reference requirement ID in commit body if helpful