commit-conventions

name	commit-conventions
description	Automatically detects and follows project commit conventions when making git commits. Checks for commitlint configuration and enforces conventional commits when present, otherwise falls back to user preferences. Use when this capability is needed.
metadata	{"author":"bengry"}

Commit Conventions

Background skill that ensures commit messages follow the project's conventions.

Detection (run before every commit)

1. Check for commitlint config: .commitlintrc*, commitlint.config.*, or @commitlint/* in devDependencies/dependencies.
2. If found → use Conventional Commits format (below).
3. If not found → follow the user's CLAUDE.md commit preferences (e.g., plain messages, no semantic prefixes).

Conventional Commit Format

When commitlint is detected, use this format:

<type>(<scope>): <subject>

[optional body]

[optional footer(s)]

Types

Type	Purpose
feat	New feature
fix	Bug fix
docs	Documentation only
style	Formatting, whitespace (not CSS)
refactor	Code change that neither fixes a bug nor adds a feature
perf	Performance improvement
test	Adding or updating tests
build	Build system or external dependencies
ci	CI configuration
chore	Other changes that don't modify src or test
revert	Reverts a previous commit

Subject rules

• Imperative mood ("add", not "added" or "adds")
• Lowercase first letter
• No period at the end
• Max 70 characters (type + scope + subject combined)

Scope

• Optional, describes the area of change (e.g., feat(auth): ..., build(deps): ...)
• Use the most specific relevant scope

Body

• Separated from subject by a blank line
• Explain what and why, not how
• Wrap at 100 characters

Breaking changes

• Add ! after type/scope: feat(api)!: remove deprecated endpoints
• Or use BREAKING CHANGE: footer with description

Reverts

• Format: revert: <subject of reverted commit>
• Body should contain: This reverts commit <hash>.

Hook Discipline

• NEVER use --no-verify unless the user explicitly asks for it.
• If a pre-commit or commit-msg hook fails, fix the root cause (reformat the message, fix lint errors, etc.) instead of bypassing hooks.
• If a commitlint hook rejects the message, rewrite the message to comply and retry.

Post-Commit Verification

If commitlint is available in the project (npx commitlint --help succeeds), run after committing:

npx commitlint --last

If this fails, amend the commit with a corrected message.

---

Source: bengry/typedash — distributed by TomeVault.