Create commit messages following good conventions. Use when committing code changes, writing commit messages, or formatting git history. Follows conventional commits and best practices.
/plugin marketplace add sontek/agent-skills/plugin install agent-skills@agent-skills-localThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Follow these conventions when creating commits.
Before committing, always verify you're on the correct branch.
# Check current branch
git branch --show-current
CRITICAL: If on main or master, you MUST create a feature branch first before committing.
Branch names follow the pattern: <type>/<short-description>
feat/add-user-auth, fix/null-pointer, ref/extract-validation# Create and switch to new branch
git checkout -b <type>/<short-description>
See the create-branch skill for complete branch naming conventions.
Example:
# Bad - committing directly to main
git branch --show-current # main
git commit -m "feat: Add user authentication" # Don't do this!
# Good - create feature branch first
git branch --show-current # main
git checkout -b feat/add-user-auth
git commit -m "feat(auth): Add user authentication"
Before committing, always review what you're about to commit:
# See what files have changed
git status
# Review all changes
git diff
# Review staged changes only
git diff --cached
# Review recent commit history for style consistency
git log --oneline -10
Verify:
# Stage specific files
git add path/to/file1 path/to/file2
# Stage all changes (use cautiously)
git add .
# Stage all changes in a directory
git add src/components/
Follow the format below, ensuring the message clearly explains what and why.
After committing:
# Verify the commit looks correct
git show
# Check commit history
git log -1
<type>(<scope>): <subject>
# ################### 50 chars is here: #
<body>
# Wrap at 72 chars ################################## which is here: #
<footer>
Note: While conventional commits allow up to 100 characters, limiting to 50-72 makes messages more readable in terminal, GitHub UI, and git log outputs.
Choose the type that best describes your change:
| Type | When to Use |
|---|---|
feat | New feature or functionality for users |
fix | Bug fix that corrects incorrect behavior |
ref | Code refactoring with no behavior change |
perf | Performance improvement (faster, less memory, etc.) |
docs | Documentation changes only (README, comments, etc.) |
test | Adding or correcting tests |
build | Build system, dependencies, or tooling (npm, webpack, etc.) |
ci | CI/CD configuration (GitHub Actions, Jenkins, etc.) |
chore | Maintenance tasks, cleanup, or housekeeping |
style | Code formatting, white space, missing semicolons (no logic) |
revert | Reverts a previous commit |
meta | Repository metadata (package.json version, etc.) |
license | License changes |
Use feat when:
Use fix when:
Use ref when:
Use perf when:
The scope specifies which part of the codebase is affected. Common scopes:
api, auth, dashboard, cliUserProfile, Header, Buttonbilling, notifications, searchmodels, views, controllersOmit scope when the change affects multiple areas or the entire codebase.
The subject line is a concise summary of the change.
# Good - specific, imperative, under 50 chars
feat(auth): Add OAuth2 support for Google login
fix(api): Handle null response in user endpoint
ref(database): Extract query builder to separate module
# Bad - vague, wrong tense, or too long
fix: bug fix # Too vague
feat: added new feature # Past tense
feat(api): endpoint for user profile management and settings # Too long
The body provides detailed context about the change.
feat(alerts): Add Slack thread replies for alert updates
When an alert is updated or resolved, post a reply to the original
Slack thread instead of creating a new message. This keeps related
notifications grouped together and reduces noise in the channel.
Users can still see the full alert history in a single thread.
fix(api): Handle null response in user endpoint
The user API returns null for deleted accounts, which caused the
dashboard to crash when accessing user properties. Add null check
before accessing user.profile to prevent the error.
The dashboard now shows a "User not found" message instead of
crashing.
Fixes ENG-5678
# Wrap at 72 chars ################################## which is here: #
The user API returns null for deleted accounts, which caused the
dashboard to crash when accessing user properties.
The footer contains metadata about the commit.
Link to issues or tickets using these formats:
Fixes GH-1234 # Closes GitHub issue #1234
Fixes #1234 # Closes issue in current repo
Closes #1234 # Same as Fixes
Resolves #1234 # Same as Fixes
Fixes ENG-1234 # Closes Jira ticket ENG-1234
Refs LINEAR-ABC-123 # References Linear issue (no close)
Refs #1234 # References issue (no close)
When to use:
Fixes/Closes/Resolves: Automatically closes the issue when mergedRefs: Links to issue without closing (for related work)Credit all contributors to the commit:
Co-authored-by: Jane Smith <jane@example.com>
Co-authored-by: John Doe <john@users.noreply.github.com>
When to include:
AI Attribution Policy:
The Co-authored-by line is the ONLY acceptable indicator of AI involvement in commits. This is the standard, professional way to credit all contributors including AI assistants.
Do NOT include ANY of the following in commit messages:
Why: Commit messages should focus on what changed and why, not how the code was written. The Co-authored-by line provides appropriate attribution without cluttering the commit history or making assumptions about the development process. Many developers use AI tools as part of their workflow, and commit messages should remain clean and professional.
For breaking changes, use one of these formats:
BREAKING CHANGE: Description of what broke and migration path
Or add ! after the type/scope:
feat(api)!: Remove deprecated v1 endpoints
Fixes ENG-5678
Refs #1234
Co-authored-by: Jane Smith <jane@example.com>
feat(alerts): Add Slack thread replies for alert updates
When an alert is updated or resolved, post a reply to the original
Slack thread instead of creating a new message. This keeps related
notifications grouped together and reduces noise in the channel.
Users can still see the full alert history in a single thread.
Refs GH-1234
Co-authored-by: Jane Smith <jane@example.com>
fix(auth): Prevent session timeout during active use
Sessions were timing out after 30 minutes even if the user was
actively using the app. Update the session middleware to refresh
the timeout on each authenticated request.
This prevents users from being logged out while working.
Fixes ENG-5678
feat(api)!: Remove deprecated v1 endpoints
Remove all v1 API endpoints that were deprecated in version 23.1.
The v2 API has been stable for 6 months and all known clients have
migrated.
BREAKING CHANGE: v1 endpoints no longer available. Clients must use
v2 endpoints. See migration guide at docs/api/v1-to-v2-migration.md
Fixes ENG-9999
Co-authored-by: John Doe <john@example.com>
Each commit should represent a single logical change:
Good (atomic):
Bad (not atomic):
| Mistake | Bad Example | Good Example |
|---|---|---|
| Too vague | fix: bug fix | fix(auth): Prevent double login |
| Wrong tense | feat: Added feature | feat: Add feature |
| Too long | feat: Add endpoint for X, Y, Z | Use body for details |
| No context | fix: Fix bug (no body) | Include body explaining what/why |
| Too verbose | Long narrative in body | Concise facts: what changed and why |
| Not imperative | fixing, fixed, adds | fix, add, update |
When creating commits:
git status to see which files changedgit diff to review all changes before staginggit diff --cached to review staged changes before committinggit log --oneline -10 to see recent commit message stylegit add path/to/filegit show after committing to verify the commit looks correctgit commit --amend ONLY for the most recent unpushed commitDo NOT use interactive commands:
git add -i - interactive staginggit add -p - patch modegit rebase -i - interactive rebase-i or --interactive flagThese require interactive terminal input which is not supported. Use specific
file paths with git add instead.
Before committing, verify:
main or master (create feature branch first: git checkout -b <type>/<short-description>)