git-conventions
Ensures all git commits follow a standardized format including types, scopes, and body requirements.
Install
mkdir -p .claude/skills/git-conventions-mikeleppane && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/12009" && unzip -o skill.zip -d .claude/skills/git-conventions-mikeleppane && rm skill.zipInstalls to .claude/skills/git-conventions-mikeleppane
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Git commit conventions with enforced scopes, conventional commits, and meaningfulKey capabilities
- →Format commit messages according to Conventional Commits
- →Enforce required scopes in commit messages
- →Use specific types for different changes (feat, fix, refactor, perf, docs, test, build, ci, chore)
- →Indicate breaking changes with `!` and a `BREAKING CHANGE:` footer
- →Write descriptive body text explaining the 'why' of a change
How it works
This skill provides guidelines for writing git commit messages that follow Conventional Commits, requiring specific types and scopes. It details the structure for subject, body, and footer, including how to mark breaking changes.
Inputs & outputs
When to use git-conventions
- →Standardize commit messages
- →Enforce scope-based commits
- →Format complex pull requests
About this skill
Git Commit Conventions
Format: Conventional Commits | Scopes: Required | Breaking changes:
!suffix + footer
Commit Message Format
Every commit message follows this structure:
<type>(<scope>): <subject>
<body>
<footer>
All three parts matter. The subject line gets people's attention, the body tells the story, the footer records breaking changes and references.
Subject Line
feat(editor): add multi-cursor support for batch edits
- Max 72 characters — truncated in
git log --onelineand GitHub UI otherwise - Lowercase — no capital first letter after the colon
- Imperative mood — "add" not "added" or "adds". Read it as: "this commit will add multi-cursor support"
- No trailing period
- Be specific — describe what changed, not what you did. "fix query timeout" not "fix bug" or "update code"
Types
Use exactly these types — no others:
| Type | When to use |
|---|---|
feat | New feature or capability for the user |
fix | Bug fix — something was broken, now it works |
refactor | Code restructuring with no behavior change |
perf | Performance improvement with no behavior change |
docs | Documentation only — README, doc comments, specs, plans |
test | Adding or updating tests with no production code change |
build | Build system, dependencies, Cargo.toml changes |
ci | CI/CD pipeline configuration |
chore | Maintenance that doesn't fit above — formatting, linting, tooling config |
Choosing the right type:
- Changed behavior? →
featorfix - Same behavior, different structure? →
refactor - Same behavior, faster? →
perf - Only tests changed? →
test - Only docs changed? →
docs
Scopes (Required)
Every commit must include a scope that identifies the area of the codebase affected. Scopes should be short, lowercase, and consistent.
Application scopes:
| Scope | Area |
|---|---|
app | Application state, event loop, top-level orchestration |
db | Database connection, query execution, channels |
schema | Schema tree panel, table/column/index loading |
editor | SQL editor panel, syntax highlighting, buffer management |
results | Results panel, table rendering, column sizing |
detail | Record detail panel, row inspection |
explain | Query explain/analysis panel |
er | ER diagram panel |
pragmas | Pragma viewer/editor panel |
dbinfo | Database info panel |
data-editor | Inline data editing, DML generation, staged changes |
history | Query history storage and search |
theme | Theming, colors, styling |
config | Configuration loading, defaults, file I/O |
cli | CLI argument parsing, entry point |
nav | Navigation, focus management, keybindings |
clipboard | Clipboard integration |
ui | Shared UI components, layout, widgets |
Infrastructure scopes:
| Scope | Area |
|---|---|
deps | Dependency additions, removals, or upgrades |
ci | CI/CD pipeline |
release | Version bumps, changelogs, release prep |
tooling | Dev tooling, linting config, formatters |
When a change spans multiple areas, use the scope of the primary change. If genuinely
cross-cutting, use app.
Scopes will evolve as the project grows — add new ones when a new module or area emerges that doesn't fit existing scopes. Keep them short and descriptive.
Body
The body explains why this change exists, not what it does (the diff shows that).
feat(results): add horizontal scrolling for wide result sets
Tables with many columns were clipped at the terminal edge, making it
impossible to inspect columns beyond the visible width. Users had to
resize their terminal or reduce font size as a workaround.
Track a horizontal scroll offset per result set and shift the visible
column window with left/right arrow keys. Column headers scroll in
sync with data rows.
Body guidelines:
- Wrap at 72 characters — respects
git logformatting in terminals - Blank line between subject and body
- First paragraph: the problem or motivation. What was wrong, missing, or needed? Why does this change exist?
- Second paragraph (optional): the approach. How does this change solve the problem? Only include when the approach isn't obvious from the diff — architectural decisions, tradeoffs made, alternatives considered and rejected.
- Skip the body only for truly trivial changes: typo fixes, import cleanup, formatting. If you're tempted to skip it, the commit might be too small or you might be underestimating the future reader's need for context.
Breaking Changes
For changes that break the public API or change user-facing behavior in incompatible ways:
- Add
!after the scope in the subject line - Add a
BREAKING CHANGE:footer explaining what broke and how to migrate
feat(config)!: change config file format from JSON to TOML
The configuration file format has changed to TOML for better readability
and comment support.
BREAKING CHANGE: config.json is no longer read. Rename to config.toml
and convert the syntax. See docs/migration.md for a conversion guide.
Both the ! marker and the footer are required — the ! for quick scanning in git log,
the footer for migration details.
What Makes a Good Commit
Atomic commits
Each commit should be a single logical change that compiles and passes tests on its own. If you're writing "and" in your subject line, consider splitting.
Good — one concern per commit:
refactor(db): extract connection pool into dedicated module
feat(db): add connection retry with exponential backoff
test(db): add connection pool timeout tests
Bad — multiple concerns bundled:
feat(db): refactor connection pool and add retry logic and tests
Commit the why, not the what
The diff shows exactly what changed. The commit message should answer: "Six months from
now, when someone reads git blame on this line, what context will they need?"
Things to Avoid
- Vague messages: "fix bug", "update code", "changes", "WIP", "misc"
- Referencing conversations: "as discussed", "per review feedback", "Claude suggested"
- Temporal language: "now we do X", "previously this was Y"
- Implementation narration: "first I changed X, then I updated Y"
- Emoji in commit messages
- Ticket/issue numbers in the subject — put them in the footer if needed:
Refs: #42
Footer
Footers go after the body, separated by a blank line. Use them for:
BREAKING CHANGE: description of what broke and migration path
Refs: #123, #456
Closes: #789
Only include footers when they carry information. Don't add empty footers.
Commit Workflow
When creating a commit:
- Review staged changes — make sure the diff matches a single logical change
- Choose the right type — use the type table above
- Pick the scope — which area of the codebase is primarily affected?
- Write a specific subject — what does this commit do, in imperative mood?
- Write the body — why does this change exist? What problem does it solve?
- Check for breaking changes — does this change user-facing behavior incompatibly?
- Verify the commit compiles — never commit code that doesn't build
When not to use it
- →When creating vague commit messages like 'fix bug' or 'changes'
- →When referencing conversations like 'as discussed' or 'Claude suggested'
- →When using temporal language like 'now we do X' or 'previously this was Y'
Limitations
- →Commit messages must be max 72 characters in the subject line
- →Commit messages must use lowercase for the subject line
- →Commit messages must be in imperative mood
How it compares
This skill enforces a structured and meaningful git commit history, improving readability and maintainability, unlike an unstructured approach that can lead to vague or inconsistent messages.
Compared to similar skills
git-conventions side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| git-conventions (this skill) | 0 | 4mo | Review | Beginner |
| resolve-conflicts | 81 | 8mo | Review | Intermediate |
| dependency-upgrade | 26 | 5mo | Review | Intermediate |
| git-commits | 21 | 4mo | No flags | Beginner |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
resolve-conflicts
antinomyhq
Use this skill immediately when the user mentions merge conflicts that need to be resolved. Do not attempt to resolve conflicts directly - invoke this skill first. This skill specializes in providing a structured framework for merging imports, tests, lock files (regeneration), configuration files, and handling deleted-but-modified files with backup and analysis.
dependency-upgrade
wshobson
Manage major dependency version upgrades with compatibility analysis, staged rollout, and comprehensive testing. Use when upgrading framework versions, updating major dependencies, or managing breaking changes in libraries.
git-commits
bonny
Create well-structured git commits in logical chunks following best practices
git-advanced-workflows
wshobson
Master advanced Git workflows including rebasing, cherry-picking, bisect, worktrees, and reflog to maintain clean history and recover from any situation. Use when managing complex Git histories, collaborating on feature branches, or troubleshooting repository issues.
github-multi-repo
ruvnet
Multi-repository coordination, synchronization, and architecture management with AI swarm orchestration
git-workflow-enforcer
CrazyDubya
Ensures commits follow conventional commits, branch naming conventions, and PR templates. Use when creating commits, branches, or PRs, or when user mentions git workflow.