marco-souza Git Commit Message Formatter
Format all commit messages using this specification.
Note: This skill uses simplified types (
fea,fix,ref,ai,oth) rather than full Conventional Commits (feat,fix,refactor,chore,docs, etc.) for brevity in AI-generated messages.
Format
<type>(optional scope): <description>
All lowercase except proper nouns. No period at the end.
Types
| Type | Use when |
|---|---|
fea |
Adding a new feature |
fix |
Fixing a bug |
ref |
Refactoring or restructuring code |
ai |
AI-related changes (prompts, models, agents) |
test |
Adding or correcting tests |
oth |
Documentation, config, or anything else |
Rules
- Description must be in imperative mood ("add feature", not "added feature")
- No period at the end
- Keep the first line under 72 characters
- Add scope only when it clarifies which component changed
- For breaking changes, append a footer:
BREAKING CHANGE: <description>
Examples
Standard Commits
fea: add user authentication flow
fix(api): handle null response from downstream service
ref: extract validation logic into shared helper
ai: update system prompt for code review skill
oth: update README with setup instructions
Breaking Change Example
fea(api)!: remove legacy authentication endpoint
BREAKING CHANGE: /api/v1/auth endpoint removed. Use /api/v2/auth instead.
Full Workflow Example
User: "Commit my changes"
Agent:
- Runs
git diff --cached— sees staged changes - Identifies dominant change: new feature in auth module
- Generates:
fea(auth): add JWT token refresh flow - Asks: "Commit with message:
fea(auth): add JWT token refresh flow?" - Runs:
git commit -m "fea(auth): add JWT token refresh flow"
Process
- Ensure we're in a git repository (
git status) - Run
git diff --cachedto see staged changes - Determine the dominant type from the table above
- Identify the scope if multiple components exist
- Write a concise description
- Ask the user to confirm or run
git commit -m "<message>"
Edge Cases
No Staged Changes
If git diff --cached is empty, check git diff for unstaged changes. Ask the user if they want to:
- Stage all changes:
git add -A - Stage specific files:
git add <files> - View changes first:
git diff
Empty Repository
If git status shows "not a git repo", initialize with git init or alert the user.
Commit Failure
If git commit fails (e.g., pre-commit hook rejection), surface the error and ask if the user wants to:
- Fix the issue and retry
- Bypass the hook:
git commit --no-verify