Master Commit Suite
Battle-tested skill for analyze, staged, unstaged, changes. Includes structured workflows, validation checks, and reusable patterns for git.
Master Commit Suite
A comprehensive skill for writing excellent git commit messages ā covering conventional commit formats, semantic versioning alignment, multi-line messages, co-authored commits, and commit message templates that maintain a clean and informative project history.
When to Use This Skill
Choose Master Commit Suite when you need to:
- Write clear, consistent git commit messages
- Follow conventional commit format (feat, fix, chore, etc.)
- Create commit messages for complex changes spanning multiple files
- Maintain a project history that's useful for changelogs and debugging
- Set up commit message templates and hooks for teams
Consider alternatives when:
- You need PR descriptions (use a PR template skill)
- You need changelog generation (use a release management skill)
- You need git workflow guidance (use a git workflow skill)
Quick Start
# Write a conventional commit git commit -m "feat(auth): add OAuth2 login with Google provider Implement Google OAuth2 authentication flow including: - Authorization URL generation with PKCE - Callback handler with token exchange - User profile fetching and account linking - Session creation after successful auth Closes #142"
# Commit Message Structure ## Format <type>(<scope>): <subject> <body> <footer> ## Example Breakdown - **Type**: feat (new feature) - **Scope**: auth (authentication module) - **Subject**: add OAuth2 login with Google provider - **Body**: Details about what was implemented - **Footer**: References (Closes #142)
Core Concepts
Conventional Commit Types
| Type | When to Use | Semver Impact |
|---|---|---|
feat | New feature for the user | Minor (0.X.0) |
fix | Bug fix for the user | Patch (0.0.X) |
docs | Documentation only changes | None |
style | Formatting, no code change | None |
refactor | Code change that's not feat or fix | None |
perf | Performance improvement | Patch |
test | Adding or correcting tests | None |
chore | Build process, tooling changes | None |
ci | CI/CD configuration changes | None |
revert | Reverting a previous commit | Depends |
Subject Line Rules
## Subject Line Guidelines ### Do - Use imperative mood: "add" not "added" or "adds" - Keep under 50 characters (72 max) - Lowercase first letter (after type prefix) - No period at the end - Describe WHAT, not HOW ### Don't - "Fixed the bug" ā "fix: resolve null pointer in user lookup" - "Updated stuff" ā "refactor(api): simplify error handling" - "Changes" ā "feat(dashboard): add real-time metric charts" ### Imperative Mood Test Your subject should complete: "If applied, this commit will ___" ā "If applied, this commit will add OAuth2 login" ā "If applied, this commit will added OAuth2 login"
Commit Body Guidelines
## When to Include a Body ### Required When: - The subject alone doesn't explain the change - Multiple files or modules were modified - The change has non-obvious reasoning - Breaking changes are introduced ### Body Structure 1. Explain WHAT changed and WHY (not how ā the diff shows how) 2. Wrap lines at 72 characters 3. Use bullet points for multiple items 4. Reference related issues or discussions ### Example with Body feat(payment): switch from Stripe Checkout to Payment Intents Payment Intents API provides better control over the payment flow, including: - 3D Secure authentication handling - Split payments for marketplace sellers - Webhook-based status tracking Stripe Checkout sessions are deprecated for our use case as of Stripe API 2024-12-01. Migration guide: docs/payment-migration.md Closes #287, #291
Breaking Change Format
## Breaking Changes ### In Footer feat(api): change authentication to Bearer tokens BREAKING CHANGE: API authentication now uses Bearer tokens instead of API keys. All clients must update their Authorization header format from: X-API-Key: <key> to: Authorization: Bearer <token> ### In Type (Shorthand) feat(api)!: change authentication to Bearer tokens (The "!" after scope indicates a breaking change)
Configuration
| Parameter | Description | Example |
|---|---|---|
format | Commit message format | "conventional" |
max_subject | Maximum subject line length | 50 |
max_body_line | Maximum body line wrap length | 72 |
require_scope | Require scope in commit type | true |
require_body | Require body for non-trivial commits | true |
allowed_types | Allowed commit types | ["feat","fix","chore"] |
Best Practices
-
Write the subject in imperative mood ā "Add feature" not "Added feature." The subject should complete: "If applied, this commit will ___." This matches git's own conventions (e.g., "Merge branch X" not "Merged branch X").
-
Keep the subject under 50 characters ā Short subjects display fully in
git log --oneline, GitHub commit lists, and email notifications. If you need more than 50 characters, move detail to the body. The subject is the headline, not the article. -
Explain why, not how, in the body ā The diff shows how the code changed. The commit message should explain why the change was made. "Switched to Payment Intents because Checkout is deprecated" is useful context that the diff cannot convey.
-
One logical change per commit ā A commit that "adds user auth, fixes bug in cart, and updates README" is impossible to revert partially, bisect for bugs, or review meaningfully. Make atomic commits that each represent one complete change.
-
Reference issue numbers in the footer ā Use
Closes #123,Fixes #456, orRelates to #789to create traceability between commits and issues. This enables automatic issue closing in GitHub and provides context for future developers reading the history.
Common Issues
Commit messages are all "fix stuff" or "update code" ā Vague messages make the commit history useless for debugging and archaeology. Use a pre-commit hook or commit template that enforces conventional commit format. Most teams see improvement within a week of adopting a standard format with enforcement.
Body text is a copy-paste of the diff ā Listing every changed line in the commit body duplicates the diff and helps nobody. The body should add context that the code cannot express: business reasoning, migration notes, trade-off decisions, and references to discussions.
Breaking changes are not communicated ā When an API contract changes, a database migration is required, or a configuration format changes, the commit message must flag this prominently. Use BREAKING CHANGE: in the footer or ! after the scope. Buried breaking changes cause production incidents when teammates deploy without reading the full diff.
Reviews
No reviews yet. Be the first to review this template!
Similar Templates
Full-Stack Code Reviewer
Comprehensive code review skill that checks for security vulnerabilities, performance issues, accessibility, and best practices across frontend and backend code.
Test Suite Generator
Generates comprehensive test suites with unit tests, integration tests, and edge cases. Supports Jest, Vitest, Pytest, and Go testing.
Pro Architecture Workspace
Battle-tested skill for architectural, decision, making, framework. Includes structured workflows, validation checks, and reusable patterns for development.