| name | git-conventional-commits |
| description | ALWAYS use this skill when committing code changes. Creates commits following conventional commit format. Trigger on any commit, git commit, save changes, or commit message task. |
Follow these conventions when creating commits.
Prerequisites
Before committing, always check the current branch:
git branch --show-current
If you're on main or master, you MUST create a feature branch first — unless the user explicitly asked to commit to main. Do not ask the user whether to create a branch; just proceed with branch creation.
Format
<type>(<scope>): <subject>
<body>
<footer>
The header is required. Scope is optional. All lines must stay under 100 characters.
Commit Types
| Type | Purpose |
|---|
feat | New feature |
fix | Bug fix |
refactor | Refactoring (no behavior change) |
perf | Performance improvement |
docs | Documentation only |
test | Test additions or corrections |
build | Build system or dependencies |
ci | CI configuration |
chore | Maintenance tasks |
style | Code formatting (no logic change) |
Valid Scopes (Examples)
Scopes should reflect the project's modules or feature areas. Examples:
(api) - API endpoints or external interfaces(auth) - Authentication and authorization(core) - Core business logic(ui) - User interface components(db) - Database layer(scripts) - Utility scripts
Subject Line Rules
- Use imperative, present tense: "Add feature" not "Added feature"
- Capitalize the first letter
- No period at the end
- Maximum 70 characters
Body Guidelines
- Explain what and why, not how
- Use imperative mood and present tense
- Include motivation for the change
- Contrast with previous behavior when relevant
- Use real newlines in commit bodies; never include literal
\n sequences
Commit Command Hygiene
When creating commits from the CLI, do not embed escaped newlines like \n inside -m strings. That produces literal backslash characters in the final commit message.
Prefer one of these patterns:
git commit -m "type(scope): Subject" \
-m "First paragraph with real line wrapping.
Second paragraph.
Co-Authored-By: (the agent's name and attribution byline)"
git commit
Use the editor flow when the message needs careful formatting.
AI-Generated Changes
When changes were primarily generated by a coding agent, include the Co-Authored-By attribution in the commit footer. Agents should use their own identity:
Co-Authored-By: (the agent's name and attribution byline)
Example: Co-Authored-By: Claude Sonnet 4 <noreply@example.com>
This is the only indicator of AI involvement that should appear in commits. Do not add phrases like "Generated by AI", "Written with Claude", or similar markers in the subject, body, or anywhere else in the commit message.
Simple fix
fix(api): Handle null response in user endpoint
The user API could return null for deleted accounts, causing a crash
in the dashboard. Add null check before accessing user properties.
Co-Authored-By: (the agent's name and attribution byline)
Feature with scope
feat(auth): Add role-based access control for admin endpoints
Restrict admin-only API routes to users with the 'admin' role.
Previously any authenticated user could access these endpoints.
Refactor
refactor(viz): Extract common plot styling logic
Move matplotlib styling logic into a shared helper function. No behavior change.
Co-Authored-By: (the agent's name and attribution byline)
Principles
- Each commit should be a single, stable change
- Commits should be independently reviewable
- The repository should be in a working state after each commit
