# Commit Style

> Team commit-message conventions. Use when writing a commit message, committing or amending changes, or when asked about the project's commit format. Reads the per-project style from .claude/idev/commit-style.md.

- Skill: `theophiluschinomona/commit-style` (Agent Skill)
- Install (CLI): `npx skillmds@latest add theophiluschinomona/commit-style`
- Raw SKILL.md: https://api.skillmd.com/api/skills/theophiluschinomona/commit-style/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: TheophilusChinomona (https://skillmd.com/u/theophiluschinomona)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/theophiluschinomona/commit-style

---


# Commit Style — Team Commit Message Conventions

Write commit messages that pass the team's `commit-msg` hook on the first try
and read well in `git log` years later.

## Procedure

1. **Read the project's style file first**: `.claude/idev/commit-style.md`.
   If it exists, its rules override everything below. If it doesn't exist,
   apply the defaults below (and mention that `/idev:hooks install-git-hooks`
   sets up the style file + enforcement hooks).

2. **Derive the ticket ID from the branch name** when the style requires one:
   `git branch --show-current`, extract the first `ABC-123`-shaped token.
   The `prepare-commit-msg` hook does this automatically too — don't add the
   prefix twice.

3. **Write the message**:
   - Subject: `type(scope): imperative summary` — conventional-commit types
     (`feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`,
     `chore`), ≤ 72 chars, no trailing period.
   - Body (for anything non-trivial): the **why**, not a list of what — the
     diff already shows what. Wrap at ~72 columns.
   - Trailers last, each on its own line (`Co-Authored-By:`, `Refs:`), per
     the team's policy in the style file.

4. **Check before committing**: if `.git/hooks/commit-msg` exists, the message
   must match its pattern (default: optional `ABC-123: ` ticket prefix +
   conventional-commit subject). If the hook rejects a commit, fix the
   message — never bypass with `--no-verify` unless the user explicitly asks.

## Defaults (when no style file exists)

```
feat(auth): add refresh-token rotation

Sessions died after 15 minutes because the access token was never
refreshed. Rotate the refresh token on each renewal per OWASP.

Refs: ABC-123
```

## Pull request format

When creating a PR (any platform — `az repos pr create` on Azure DevOps,
`gh pr create` on GitHub), unless `.claude/idev/commit-style.md` overrides:

- **Title**: same convention as the commit subject (ticket prefix + typed
  imperative summary). For a single-commit branch, reuse the subject.
- **Description**:

```markdown
## What
2-4 bullets of user-visible change (not a commit list — the platform shows those).

## Why
The problem/ticket context in 1-3 sentences.

## Testing
What was actually run: build, tests, browser-test report path if UI.

## Notes for reviewer
Risky spots, decisions needing eyes, rollback hint. Omit if none.
```

## Anti-patterns

- "fix stuff", "wip", "updates" — the hook rejects these; so should you.
- Restating the diff in the body.
- Bundling unrelated changes to share one message — split the commits.