| name | writing-git-commits |
| description | Expert guide to writing semantic commit messages following the Conventional Commits specification. Master clear, machine-readable commits that communicate intent and drive automation. |
Writing Great Git Commits
You are mastering the art of semantic commit messages that communicate intent to both humans and machines. Follow the Conventional Commits specification to create commits that enable automated tooling, clear history, and effective collaboration.
What is Conventional Commits?
Conventional Commits is a lightweight specification for adding human and machine-readable meaning to commit messages. It provides a simple set of rules for creating an explicit commit history that:
- Enables automated tools to parse and act on commits
- Makes it easier to understand code history at a glance
- Aligns with Semantic Versioning (SemVer) for automated release management
- Drives more organized development practices
Child Skills
-
Summary: Quick overview of the specification and core concepts
- → See
./summary/SKILL.md
- or if needed
skill_use(superpowers_writing_git_commits_summary)
-
Examples: Real-world commit message examples for different scenarios
- → See
./examples/SKILL.md
- or if needed
skill_use(superpowers_writing_git_commits_examples)
-
Specification: Complete technical specification with all rules and requirements
- → See
./specification/SKILL.md
- or if needed
skill_use(superpowers_writing_git_commits_specification)
-
FAQ: Frequently asked questions and practical guidance
- → See
./faq/SKILL.md
- or if needed
skill_use(superpowers_writing_git_commits_faq)
Basic Structure
Every commit message should follow this format:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Core Commit Types
- feat: Introduces a new feature (maps to
MINOR in SemVer)
- fix: Patches a bug (maps to
PATCH in SemVer)
- BREAKING CHANGE: Major breaking change (maps to
MAJOR in SemVer)
- docs: Documentation changes
- style: Code style changes (formatting, missing semicolons, etc.)
- refactor: Code refactoring without feature changes
- perf: Performance improvements
- test: Adding or updating tests
- chore: Build, dependencies, or tooling changes
- ci: CI/CD configuration changes
When to Use This Skill
Use the Conventional Commits specification when:
- Creating semantic commit messages for version-controlled code
- Working in teams that need clear commit history
- Building automated tools that parse commit messages
- Integrating with semantic versioning practices
- Generating automated CHANGELOGs
- Communicating the nature of changes to stakeholders
How to Apply It
- Read the Summary for quick understanding of the core concept
- Review Examples to see how different scenarios map to commit types
- Check the Specification for detailed rules and technical requirements
- Consult the FAQ for answers to common questions and best practices
Key Principles
✅ Be Clear: Commit messages should clearly communicate what changed and why
✅ Be Consistent: Use the same convention across all commits
✅ Be Structured: Follow the type/scope/description format
✅ Be Atomic: One logical change per commit when possible
✅ Be Machine-Readable: Enable automated tooling and analysis
Integration with Your Workflow
This skill is referenced by /project:do:commit to guide the creation of semantic commits that maintain a clear, organized commit history and enable automated tooling for release management and changelog generation.
License: Creative Commons - CC BY 3.0
Source: Conventional Commits v1.0.0
